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NTRODUCTI0N 


OS/2 is a long-anticipated operating system written specifi¬ 
cally for the present and future generations of microcom¬ 
puters. Designed to run on a broad base of machines and to 
offer a large array of features, it is an ambitious operating sys¬ 
tem and represents a major advancement over MS-DOS. 

OS/2 is a system that is both familiar and unique. Many 
of its features are familiar because they have migrated either 
up from MS-DOS or down from minicomputer operating sys¬ 
tems. Much of OS/2 is unique, however, because it is tailored 
to a new model of computing. The heart of this new model is a 
high-performance, multitasking personal computer, which 
can interact with the user through an efficient graphics display 
and connect to other computers and shared resources through 
a network. The designers of OS/2 anticipate that this comput¬ 
ing model will form the future basis for office automation. 



REQUIREMENTS 
AND VERSIONS 


Accordingly, you may find OS/2 to be a complex system with many 
unfamiliar features. This book is written to introduce you to the new con¬ 
cepts that underlie OS/2, and to show you how to develop OS/2 programs, 
beginning with simple examples and leading to progressively more advanced 
applications. The book is designed for programmers who want to write MS- 
DOS applications that are compatible with OS/2, who want to port MS- 
DOS programs to OS/2, or who want to create entirely new applications 
under OS/2. It should also be of interest to managers in the software indus¬ 
try determining how to position their products in the confusing ensemble of 
new development environments, and to software purchasers who want to 
understand the new features they can expect under OS/2. Finally, the book 
is written for computer enthusiasts desiring to understand this fascinating 
new operating system out of pure curiosity. 

The book emphasizes the differences between MS-DOS and OS/2. It 
also stresses applications programming rather than systems programming 
(such as writing device drivers), and writing in a high-level language (specif¬ 
ically, C) rather than programming in assembly language. Using a high-level 
language such as C hides many of the differences between MS-DOS and 
OS/2, and greatly facilitates the conversion process. The book, however, 
includes several low-level techniques and assembler routines that may be 
required to translate certain MS-DOS programs to OS/2; also, some of the 
basic concepts are explained by referring to specific machine instructions. 


The book assumes a familiarity with the C language and the basics of the 
MS-DOS operating system. If you require additional information on either 
of these topics, see the Bibliography for relevant titles. 

You will also need a compiler or assembler that supports OS/2 develop¬ 
ment. The examples in the book were prepared using the Microsoft C com¬ 
piler version 5.1 (and the Microsoft Macro Assembler version 5.1 for the 
few assembly language routines). This book, in conjunction with your com¬ 
piler, should enable you to prepare the example programs and to write your 
own simple OS/2 applications. However, for developing complex applica¬ 
tions you should obtain a development kit that includes additional software 
utilities and detailed documentation on all OS/2 functions. Microsoft pro¬ 
vides such a package, which is called the Microsoft Operating System/2 
Programmer’s Toolkit. 

You can prepare and run all the example programs using OS/2 version 
1.0 or later. The first 11 chapters in the book deal primarily with the OS/2 
kernel system, which is present in all versions. All of the program listings 
were tested under version 1.0, but should also work with later versions. 



AN OVERVIEW 
OF THE BOOK 


Chapter 12 discusses the Presentation Manager, which is supplied beginning 
with version 1.1; this chapter, however, does not contain example listings. 
Note that most of the example programs will run within a window of the 
Presentation Manager, although none of them are written specifically for 
this environment. 


Part One of this book provides the basic background information neces¬ 
sary for understanding the programming techniques presented in the fol¬ 
lowing chapters. Chapter 1 describes the essential features and structure of 
OS/2 from the viewpoint of the user or installer of the system; Chapter 2 
discusses these same topics from the viewpoint of the programmer under 
this system. 

Part Two describes the step-by-step procedures for developing programs 
for specific environments. Chapter 3 discusses the guidelines for writing an 
MS-DOS program that can also run in the DOS compatibility mode of 
OS/2. Chapter 4 then describes how to write a program specifically for the 
protected mode of OS/2, and Chapter 5 shows how to write a single pro¬ 
gram that can run under MS-DOS, in the DOS compatibility mode of 
OS/2, or under the OS/2 protected mode. 

The techniques presented in Part Two are for writing relatively simple, 
MS-DOS-style programs, or for porting programs from MS-DOS to OS/2. 
Part Three be gins the topic of developing applications that use the advanced 
and unique features of OS/2. Chapter 6 explains how to use the multitask¬ 
ing features of OS/2, so that you can create applications that consist of 
multiple threads of execution or multiple concurrent processes. Chapter 7 
then shows you how to use the interprocess communication facilities of 
OS/2 to exchange data between separate threads or processes, and to syn¬ 
chronize their activities. 

Note that the techniques discussed in Chapters 3 through 7 represent 
increasingly greater levels of commitment to the OS/2 operating system. 
The topics in these chapters range from writing MS-DOS programs that will 
run in the compatibility mode of OS/2 as secondary functions, to develop¬ 
ing advanced applications dependent upon unique OS/2 features. 

Part Four completes the discussion of OS/2 programming basics by pro¬ 
viding a systematic summary of the OS/2 application program interface. 
The chapters in this part of the book will help you find the appropriate 
functions to meet your needs, and will help you design your OS/2 applica¬ 
tions. Chapter 8 summarizes the basic kernel functions, and Chapter 9 
reviews the functions for the screen, keyboard, and mouse. 



Part Five presents the techniques for developing several special types of 
applications. Although these topics are not essential to OS/2 kernel pro¬ 
gramming, they are interesting and informative, and the example programs 
serve to illustrate many of the techniques and functions described in pre¬ 
vious chapters. Chapter 10 explains how to write dynamic-link routine 
libraries, which allow you to share code among several applications and 
effectively extend the services provided by the operating system. Chap¬ 
ter 11 presents the methods for writing OS/2 monitors, which can be used 
to implement background utilities equivalent to the familiar memory- 
resident programs under MS-DOS. Finally, Chapter 12 introduces the 
OS/2 Presentation Manager, which provides a programming environment 
under OS/2 that is similar to Microsoft Windows under MS-DOS. 

The appendices supply reference material that will be useful when read¬ 
ing this book or developing OS/2 programs. Appendix A is a glossary that 
defines many of the new terms you will encounter when working with 
OS/2. Appendix B summarizes the OS/2 services provided for application 
programs, giving the purpose for each function, the calling prototype, and 
a description of each parameter. Appendix C provides a similar summary 
for the OS/2 input/output control functions, and Appendix D gives a brief 
description of the error codes that are returned by the OS/2 services. 
Finally, the Bibliography lists a collection of titles to help you obtain back¬ 
ground information on the topics in this book, or to explore selected topics 
in greater depth. 

How to Use This Book 

If you are writing OS/2 programs, you can use the commentaries in the chap¬ 
ters of this book to gain an overview of the functions provided by OS/2, and to 
learn how they are used together within an application program. Once you 
have designed the general program structure and planned the function-calling 
sequence, you can consult Appendices B and C to determine the exact 
function-calling protocols. Finally, if an error occurs when running your pro¬ 
gram, you can look up the error code in Appendix D. 

As you begin reading this book and writing OS/2 programs, you may 
find that programming under OS/2 is surprisingly easy. Writing a program 
under OS/2 can be simpler than developing an application of equivalent 
complexity under MS-DOS; although a more complex operating system, 
OS/2 provides a wealth of efficient, well-documented services, whereas 
MS-DOS often requires you to write low-level code to compensate for its 
limitations and inefficiency. OS/2, however, can also support programs of 
greater inherent complexity than typical MS-DOS applications. I hope this 



book will serve as a starting point and will inspire you to create applications 
that are far more advanced and sophisticated than any you would attempt 
to write under MS-DOS. 


COMPANION 
DISKETTE 
AND OS/2 
PROGRAMMER'S 
TOOLS 


If you would like to avoid typing in the listings in this book, and you would 
like to be able to test, modify, or use these listings for developing your own 
programs, you can order a companion diskette. This diskette contains all 
listings in the book, including all C, assembler, header, MAKE, and defini¬ 
tion files. 

Also available is a set of programmer’s tools for developing OS/2 appli¬ 
cations, including an interactive screen designer, keyboard macro and cut- 
and-paste utilities, and a comprehensive set of functions for managing data 
input screens, windows, and menus, and for producing printed reports. 
Complete source code is provided for all utilities and functions. 

See the Diskette Offer in the back of the book for more details and for 
information on ordering these items. 
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CHAPTER 


Using OS/2 


In this chapter, you will obtain an overview of the basic features of 
OS/2. Beginning at a familiar starting point, MS-DOS, the first sec¬ 
tion summarizes the chief differences between OS/2 and MS-DOS, 
emphasizing the advantages OS/2 offers the system user. Next you 
will learn about the basic structure of OS/2 and the general relation¬ 
ships among its myriad components. The chapter then discusses the 
various versions and additions to OS/2, and illuminates the confusing 
issue of compatibilities—what type of program will run in each of the 
environments offered by MS-DOS and OS/2. Once you have grasped 
these basic concepts, the remainder of the chapter concentrates on the 
specifics of setting up and using the system, emphasizing those config¬ 
uration options and operating-system commands that are unique to 
OS/2 and new to the user converting from MS-DOS. 

This chapter thus focuses on the general organization and opera¬ 
tion of OS/2, and is presented largely from the perspective of the user 
of the system. Chapter 2 subsequently introduces OS/2 from the 
viewpoint of the programmer, explaining the important new features 
of the application program interface (API) and the steps involved in 
developing a program. 
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WHAT'S HEW 
IN OS/2 FOR 
THE USER 


In this section, you will learn about the primary new features of OS/2 that 
are not offered by MS-DOS. The descriptions throughout the remainder of 
the book also emphasize these unique aspects. There are two reasons for 
this emphasis. First, most readers are already familiar with the basic fea¬ 
tures of MS-DOS; concentrating on the new elements of OS/2 renders the 
task of explaining such a large and complex system more tractable. Second, 
converting a computer system to OS/2 can be expensive and time- 
consuming, and learning the new programming environment and develop¬ 
ing applications for this system is a challenging task. Therefore, before 
deciding to convert a machine to OS/2, or to target a software product for 
this system, you should understand the significant differences between the 
two operating systems, as well as the advantages offered by OS/2 for vari¬ 
ous types of application programs. 

The following new features of OS/2 are discussed in this section: 

♦ A new processor 

♦ Large memory space 

♦ Multitasking 

♦ Interprocess communication 

♦ Dynamic linking 

♦ Device-independent program interface 

♦ Graphics interface 

♦ New commands 

A New Processor 

The most important fundamental difference between MS-DOS and OS/2 is 
that OS/2 is written to take advantage of the advanced features of the Intel 
80286 microprocessor. MS-DOS was written to run on the Intel 8086/88 
processor, which is used in the IBM PC, PC XT, PS/2 model 30, and com¬ 
patibles. The 8086/88 was designed to run a single application at atime and 
to afford a total address space of 1 megabyte. Intel’s next major processor, 
the 80286, is used in the PC AT, PS/2 models 50 and 60, and other com¬ 
patible machines. This processor can run in two distinct modes: the real 
mode and the protected mode (these modes are described in greater 
detail in Chapter 2). The real mode closely emulates the operation of the 
8086/88; therefore, MS-DOS can run under this mode just as it runs 
on 8086/88-based machines. The real mode of the 80286 runs approxi¬ 
mately three times faster than the 8088; otherwise, it offers no additional 
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features or advantages for MS-DOS applications. The protected mode of 
the 80286, however, offers some significant enhancements, and provides 
hardware support for sophisticated operating-system features that resemble 
those in minicomputer systems. 

Because of the manner in which it was programmed, MS-DOS cannot 
run under the protected mode. OS/2, however, was written specifically to 
take advantage of the protected mode, and almost all of the new features of 
OS/2 discussed in this section, such as the large address space and applica¬ 
tion multitasking, are based on the hardware support provided by this 
mode. As a consequence of its use of the protected mode, however, OS/2 
requires the 80286 (or 80386). This operating system therefore cannot run 
on the standard IBM PC, PC XT, or compatibles. For more information on 
the hardware requirements of OS/2, see the section on Versions and Com¬ 
patibilities later in this chapter. 

Large Memory Space 

Because MS-DOS is written to run on the 8086/88 processor (or the real 
mode of the 80286 and 80386), it must abide by the 1-megabyte memory 
limit imposed by this chip. Furthermore, under MS-DOS the upper 384 
kilobytes of this memory space are reserved for the ROM BIOS (the basic 
input/output system on ROM chips) and for adapter cards (such as video 
and disk controllers). Therefore, you can install and use a maximum of 640 
kilobytes of memory for the operating system and for application pro¬ 
grams. The operating system consumes approximately 50 kilobytes, and 
any memory-resident utilities that you install further reduce available mem¬ 
ory. Consequently, there is a strict upper limit on the size of application pro¬ 
grams that can run under MS-DOS. 

Applications written specifically for OS/2, however, can run in the 
80286 protected mode. Under this mode, the processor can directly address 
16 megabytes of memory. OS/2 can therefore use up to 16 megabytes of 
physical memory installed in the machine. Furthermore, by taking advan¬ 
tage of 80286 hardware support, OS/2 can allocate to an application pro¬ 
gram more memory than is physically present in the system, up to a 
theoretical limit of 1 gigabyte per process (a gigabyte is 2 30 , or approxi¬ 
mately one billion, bytes). This enlarged memory space is known as virtual 
memory , and is maintained by swapping sectors of code and data between 
random access memory and secondary storage on a disk. The swapping 
process is invisible to application programs; if a program reads or writes to 
a sector that is not currently present in physical memory, the operating sys¬ 
tem automatically swaps in the required sector from the disk. 

Note that the 16 megabytes of physical memory that can be used by OS/2 
consist of standard, directly addressable, random access memory chips located 




Programmer’s 
Guide to OS/2 
CHI 


on the motherboard or on expansion cards. The portion of this memory at 
addresses above 1 megabyte is known as extended memory and can be installed 
only in machines using the 80286 or more advanced processors. 

Do not confuse extended memory with expanded memory , which is a 
type of memory that allows standard MS-DOS applications to access more 
than 640 kilobytes of code and data. Expanded memory is physically 
located on specially configured adapter cards, and is accessed in a manner 
defined by the Lotus/Intel/Microsoft expanded memory specifi¬ 
cation (LIM-EMS). The latest version of this specification (4.0) allows 
MS-DOS programs to access up to 32 megabytes of memory above the 
640-kilobyte limit. 

Although the expanded memory mechanism can enhance the suitability 
of MS-DOS for running large applications, it is considerably less useful 
than the large virtual address space provided by OS/2, for two reasons. 
First, the amount of memory that can be accessed through the expanded 
memory specification is considerably smaller than the OS/2 virtual mem¬ 
ory space. Second, an MS-DOS application must be specially written to use 
expanded memory. The program must explicitly map each page of ex¬ 
panded memory before it can access these pages, and it must carefully track 
the location of all its code and data segments that are stored in expanded 
memory. In contrast, OS/2 automatically performs all the details of mem¬ 
ory management, so that an application may directly and freely use all the 
virtual memory it has been allocated, without regard to its physical location 
or other details. 

Multitasking 

Unlike MS-DOS, OS/2 fully supports multitasking of application pro¬ 
grams. Under OS/2, you can load and run multiple programs simultane¬ 
ously and can switch rapidly among them, bringing one program at a time 
into the foreground. Furthermore, all of these programs continue to run , 
even when they are in the background. 

Various limited forms of multitasking have been implemented under 
MS-DOS. However, the 8088 processor provides no hardware support for 
multitasking, and multitasking systems written under DOS have tended to 
be quite restrictive and precarious. The full-featured and robust multitask¬ 
ing offered by OS/2 is possible because of the extensive hardware support 
provided by the protected mode of the 80286 processor. This mode allows 
the operating system to rapidly switch between processes, and it prevents 
one application from corrupting the memory and other resources owned by 
another application. 

Note that OS/2 is a multitasking system, but not a multiuser system, 
such as UNIX. Multiuser systems allow multiple terminals to connect to a 
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single processor, which runs a single copy of the operating system. As men¬ 
tioned in the Introduction, OS/2 was designed for high-performance 
office-automation systems, in which each user has a separate processor and 
can run multiple applications with high efficiency, ideally through a graph¬ 
ics interface. In an age of relatively inexpensive processors, it makes sense 
to share peripheral resources such as file servers and printers through a net¬ 
work, but to allocate a separate processor to each workstation. 

See Chapter 6 for details on the OS/2 multitasking mechanism and to 
learn how you can write your programs to take advantage of it. 

Interprocess Communication 

Once multiple programs can run simultaneously, the next significant 
enhancement is to allow these programs to communicate with each other. 
Under the multitasking schemes that have been implemented for MS-DOS, 
the highest goal is generally a state of peaceful coexistence between pro¬ 
grams; more commonly, applications tend to sabotage each other’s 
resources. Under OS/2, however, not only are multitasking programs pro¬ 
tected from mutual hostility, but a rich set of interprocess communication 
mechanisms allows cooperation between processes. These mechanisms 
include most forms of interprocess communication traditionally provided 
by minicomputer and mainframe multitasking operating systems, such 
as pipes, queues, shared memory, and semaphores. See Chapter 7 for a dis¬ 
cussion of interprocess communication methods and how to use them in 
your programs. 

Interprocess communication is one of several important features of 
OS/2 that allow a greater level of program modularity than was possible 
under MS-DOS. Under MS-DOS, the user must typically choose between 
running separate noncooperating programs, or installing a single, inflexible 
integrated package. Under OS/2, the computing environment can consist 
of multiple programs, which are loaded separately but can still work inti¬ 
mately together through interprocess communication. Users can select and 
combine separate modular programs to produce a carefully tailored, cus¬ 
tom software system. Dynamic linking, discussed next, adds yet another 
dimension of modularity to OS/2 applications. 

Dynamic Unking 

The dynamic linking mechanism of OS/2 provides programs direct and 
simple access both to basic operating-system services and to modules of 
services that have been supplied by third-party software developers. An 
important feature of dynamic linking is that it allows developers to provide 
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custom extensions to the operating system; programs can access the ser¬ 
vices of these extensions in the same manner that they access the services of 
OS/2 itself. Thus, OS/2 is an open operating system; custom extensions 
can be added through a well-documented interface, and without intimate 
knowledge of the inner workings of the system. Modules such as database 
systems and communications packages can be seamlessly attached to the 
operating system itself, and can be shared by all the currently installed 
application programs. 

Chapter 2 explains the basic concepts of dynamic linking, and how it dif¬ 
fers from the linking method used by MS-DOS. Chapter 10 presents the 
methods for developing dynamic-link libraries and calling the routines they 
contain from your application program. 

Device-Independent Program Interface 

Although MS-DOS is useful for loading programs, managing memory, and 
handling the file system, the set of general services that MS-DOS provides 
for application programs is limited, and many of these services are notori¬ 
ously low in performance. For example, a benchmark program presented in 
the book Performance Programming Under MS-DOS (see the Bibliogra¬ 
phy) revealed that an operating-system service for writing strings to the 
screen was approximately 250 times slower than a custom routine that 
writes directly to video memory. It is not surprising that most high- 
performance MS-DOS programs bypass the operating system and directly 
access low-level hardware resources. The consequence of this practice is 
that machines designed to run MS-DOS software must closely clone the 
original IBM hardware, leaving little room for alternative standards or 
hardware innovation. 

Unlike MS-DOS, OS/2 has a rich application programming interface 
(API). Not only does the OS/2 API provide many more functions than 
MS-DOS, but the functions generally operate at a higher level of perfor¬ 
mance. For example, the set of OS/2 video functions rival the efficiency 
and flexibility of custom-written routines that directly access video hard¬ 
ware. Consequently, under OS/2 you can now write a high-performance 
program using the operating-system interface and avoiding dependence on 
specific hardware features. Ideally, such a program will run on any machine 
that supports OS/2. Furthermore, hardware designers do not need to pre¬ 
cisely imitate a specific hardware configuration to support OS/2; OS/2 can 
run on a variety of configurations, as long as the vendor supplies the appro¬ 
priate device drivers to handle the lowest-level device-dependent opera¬ 
tions. (See Chapter 2 for a discussion of device drivers.) 



Basic Features of OS/2 


Graphics Interface 

An important element of the office-automation design mentioned in the 
Introduction is that users be able to interact with the computer system 
through an efficient graphics interface. This interface should display indi¬ 
vidual applications in windows, and offer a rich set of device-independent 
graphics functions to application programs. 

Microsoft Windows is an example of such an environment implemented 
under MS-DOS. DOS, however, provides little system support, so that 
Windows must be almost an entire operating system itself. Due to this 
lack of operating-system support, Windows offers only a limited form 
of multitasking, and suffers from a lack of performance and limited 
program memory. 

OS/2, however, is ideally suited for supporting a graphics application 
interface for several reasons. First, as mentioned above, OS/2 is modular, 
allowing a graphics environment to be seamlessly attached to the system. 
Also, the operating system itself provides many of the features required by 
the windowing environment, such as multitasking, interprocess communi¬ 
cation, and isolation of tasks. Consequently, a graphics interface can be 
closely integrated with the operating system, and can take advantage of its 
services rather than working around its inherent limitations. 

The Windows Presentation Manager is the graphics application inter¬ 
face that will be supplied with version 1.1 of OS/2. Chapter 12 introduces 
the topic of developing Presentation Manager applications. 


New Commands 

In addition to the major enhancements discussed above, OS/2 provides 
several new operating-system commands and configuration options. Many 
of these instructions control features of multitasking under OS/2; others 
are simply enhancements designed to make the operating system easier to 
use. These new commands and options are discussed in the last section of 
this chapter; you will find them easier to understand after you have learned 
the basic structure of the operating system in the next section. 


HOW OS/2 IS 
ORGANIZED: 
THE USER'S 
PERSPECTIVE 


As a complex multitasking system with a vast memory space, OS/2 consists 
of many components—many separate logical units that are concurrently 
active in memory. This section compares the structures of OS/2 and 
MS-DOS, and provides a conceptual road map to illustrate the basic com¬ 
ponents of OS/2, explaining the relationships among them, how they are 
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started, how you switch from one to the other, and where they are located in 
memory. The following fundamental components of OS/2 are discussed 
in this section: 

♦ The session manager 

♦ Multiple protected mode screen groups 

♦ A single real mode screen group 

♦ Multiple background programs 

This description of the structure of OS/2 is far from complete; it is only 
one of many viewpoints of the system, and is presented largely from the per¬ 
spective of the user or installer of the system. Chapter 2 subsequently 
explores the structure of OS/2 from the aspect of the programmer , deline¬ 
ating the many underlying layers of the operating system that support an 
application program. 

Figure 1.1 illustrates the basic components of OS/2 described in this sec¬ 
tion. The diagram shows that when OS/2 is loaded and running, it typically 
consists of a collection of screen groups , or sessions , that are controlled by a 
session manager , plus a set of background programs . A screen group is 
loosely defined as a collection of programs that share a common virtual 
screen and keyboard; screen groups, and the concept of a virtual screen and 
keyboard, will be described shortly. Figure 1.2 provides a comparable map 
for MS-DOS. Borrowing terminology from OS/2, MS-DOS consists of 
only a single “screen group”; these figures graphically demonstrate the rela¬ 
tive complexities of the two operating systems. 

The Session Manager 

The exact appearance and operation of the session manager, also known as 
the program selector, depends upon the version of OS/2 you are running. 
With all versions, however, the session manager allows you to perform two 
basic functions: 

♦ To switch into a screen group that is already loaded and running 
in memory 

♦ To start a new screen group 

When you first boot OS/2, either you will automatically enter the ses¬ 
sion manager, or you will be in a protected mode screen group (depending 
upon the current system configuration). If you are in a protected mode 
screen group, you will see a standard prompt and can type operating-system 
commands in the same manner as in MS-DOS. Whenever you are in one of 
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FIGURE 1.1: The basic components of OS/2 



Single Real Mode 
"Screen Group" 



FIGURE 1.2: The basic component of MS-DOS 


the screen groups, you can get into the session manager by pressing the Ctrl- 
Escape key combination. Ctrl-Escape is one of the sacred hotkeys under 
OS/2 that are always recognized by the system, and cannot be intercepted 
by an application program or utility. 
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SYSTEM HOTKEY 

Ctrl-Escape Activates the session manager from a screen group 

Once the session manager is activated, it takes over the entire screen and 
displays its options in one or more windows. You may now either switch 
into an existing screen group or start a new screen group. Figure 1.3 shows 
the appearance of the session manager in version 1.0 of OS/2. 


Update 


| FI=Help 


Program Selector 


Use «- or -» to move between Start a Program and Switch to a Running Program. 
Use t or i to move select bar, then press Enter. Press F10 to Update lists. 



Switch to a Running Program 


1 MS-DOS Command Prompt 
B CMD.EXE 


FIGURE 1.3: The OS/2 session manager in version 1.0 


Switching into an Existing Screen Group 

The session manager will provide a list of screen groups that are already 
loaded into memory. These screen groups are identified either by the name 
of the appropriate command interpreter or by the name of the main appli¬ 
cation running in the session. When the system is first started, two screen 
groups will typically be displayed in this list: one running in the protected 
mode and one in the real mode. When you select one of these screen groups, 
the session manager immediately disappears and the chosen screen group 
appears on the monitor. Also, all subsequent keyboard input is now read by 
a program that belongs to this screen group (except for the system hotkeys). 

Starting a New Screen Group 

The session manager also allows you to start a new protected mode screen 
group. When you start a new screen group, you may begin by executing a 
command interpreter. Once the command interpreter is running, you will 
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see a command line prompt and can either issue operating-system com¬ 
mands or run a program, just as under MS-DOS. You can also initiate a new 
screen group from the session manager by directly running a program, 
without going through a command interpreter. The session manager allows 
you to install your favorite programs in a selector list so that you can start 
one of these programs (in a new screen group) simply by selecting the appro¬ 
priate description from the list. Note that when you begin a new screen 
group from the session manager, this group is automatically activated, tak¬ 
ing over the keyboard and monitor just as in the switching procedure 
described in the last section. Figure 1.1 illustrates using the start operation 
from the session manager to insert a new screen group into the set of exist¬ 
ing screen groups that are drawn on the circumference of the circle. Note 
that the session manager can start a new screen group but cannot remove an 
existing one; the screen group must terminate itself through one of several 
methods to be described later in the chapter. 

The session manager may have other facilities, such as context-sensitive 
help, which describes the various options, procedures, and keystrokes. 
Note that in OS/2 version 1.1, the Presentation Manager (the Task Man¬ 
ager window) replaces the session manager described here; however, the 
basic screen group operations it performs are the same. 

Protected Mode Screen Groups 

You've already been introduced to the notion of a screen group, which was 
discussed in connection with the session manager that controls which of the 
screen groups is currently active. This section provides a more complete 
general definition, and then describes the structure of a screen group that 
runs in the protected mode. 

A screen group , also known as a session , is defined as a collection of 
processes that share a single virtual screen, keyboard, and mouse. Under 
OS/2, a process is an instance of the execution of a program; this program 
can be either a command interpreter, an application program, or some sec¬ 
ondary program that is started by an application program to perform a sub¬ 
sidiary task. The term process is thus roughly equivalent to the term 
program , and the two words are often used synonymously. (As you will see 
in later chapters, a process is also the entity that can own resources, such as 
memory or file handles.) 

The notion of a virtual screen, keyboard, and mouse is best explained by 
describing how a screen group interacts with the user. As seen in the last section, 
a screen group is either active (in the foreground) or inactive (in the back¬ 
ground). When it is active, all video output from any of the programs belong¬ 
ing to this group instantly appears on the screen, and programs within the 
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group have immediate access to input from the keyboard or mouse. If several 
programs in a screen group are running simultaneously and write to the screen 
at the same time, there is no mechanism to prevent them from interfering with 
each other’s video output. 

When a screen group is made inactive —that is, when it is placed in 
the background by switching into another screen group—the contents of the 
screen are saved in an internal buffer. Programs belonging to a protected 
mode screen group can continue to run even when the group is in the back¬ 
ground; they may also continue to generate video output. This output, 
however, does not go to the physical screen, but rather continues to update 
the internal buffer. (The internal buffer holds only a single screen; when the 
last line is reached, lines scroll off the “top.”) When the screen group once 
again becomes active, the updated contents of this buffer are restored to the 
physical screen. The program is therefore unaware of whether its output is 
currently visible, but simply continues to send video data to a virtual screen 
that is attached to the actual physical screen only when the screen group is in 
the foreground. 

Likewise, programs belonging to a screen group receive keyboard char¬ 
acters and mouse input from a virtual keyboard and a virtual mouse. Thus, 
programs can continue to request input from these virtual devices even 
when their screen group is in the background. The virtual devices will be 
connected with—and receive input from—the real devices only when the 
screen group is in the foreground. 

In summary, the important features of the virtual screen, keyboard, and 
mouse mechanism are the following: 

♦ A program can continue I/O operations with these devices, 
whether the program’s screen group is currently in the foreground 
or in the background. Programs do not have to save and restore 
their own screens (an exception is graphics programs, which are 
discussed in Chapter 9). 

♦ I/O from programs in separate screen groups cannot conflict. 
Thus, a program in one screen group cannot overwrite the screen 
produced by a program running in another group, or receive key¬ 
board or mouse input directed to that program. (Programs in a 
background screen group can send messages to the foreground 
screen using the “popup” video functions described in Chapter 9; 
these functions, however, automatically save and restore the over¬ 
written foreground screen.) 

♦ Programs within a single screen group access and compete for I/O 
from a single set of virtual devices. Thus, these programs can con¬ 
flict unless they voluntarily cooperate with each other, or their I/O 
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is mediated by a windowing environment such as the Presentation 
Manager (note that the Presentation Manager and the programs 
written for its interface all run in a single screen group). Typically 
only one program in a screen group, such as an editor, would need 
to interact with the user, and the other programs would be primar¬ 
ily noninteractive (such as a compiler). 

Protected mode screen groups are composed of programs that run under the 
protected mode of the 80286 processor, and therefore can participate in multi¬ 
tasking, can access the large virtual memory space, and can enjoy the other 
protected mode benefits discussed at the beginning of the chapter. Accordingly, 
you may start multiple protected mode screen groups, and even though you can 
interact with only one of these groups at a time, they all continue to run. (Under 
version 1.0, the maximum number of protected mode screen groups is 12.) For 
example, you could run a spreadsheet program in one screen group, a data 
communications application in another, and a word processor in a third. If the 
word processor is in the foreground, you could write a letter at the same time 
that the spreadsheet program performs a recalculation and the communica¬ 
tions program downloads a large file. Note that not all of the processes receive 
the same share of the CPU’s time; see Chapter 6 for a discussion of how simul¬ 
taneous processes are scheduled. 

It is important to distinguish an inactive screen group (one that is run¬ 
ning in the “background”) from a true background task. True background 
tasks do not belong to any screen group, and therefore in Figure 1.1 they are 
placed outside of the circle of screen groups; these programs are discussed 
later in this chapter. 

When you are in a screen group, you may switch to another screen group 
in one of two ways: 

♦ You can press Ctrl-Escape to go into the session manager and select a 
screen group from a list. This method was already discussed. 

♦ You can also switch immediately into another screen group by 
pressing Alt-Escape, bypassing the session manager. As illustrated 
in Figure 1.1, pressing Alt-Escape will move you around the circle 
of installed screen groups. The experience is much like flipping 
through channels on a TV set. 

SYSTEM HOTKEY 

Alt-Escape Switches directly from one screen group to another 

You can also start a new screen group from within an existing screen 
group, without going through the session manager. You must be running the 
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command interpreter (that is, you are at the operating-system command 
line prompt), and issue the START command followed by the program 
name. For example, the following command will start a program called ED 
in a new screen group: 

[C:\] start ed 

Note that when you issue this command, the current screen group remains 
in the foreground; unlike starting a screen group from within the session 
manager, the system does not automatically switch to the new screen group. 
The system command START has the syntax 

START [“session name ”] [/c] [command [arguments]} 

and starts a program running in a new screen group. Note that u session 
name ” specifies the screen group name that will be displayed by the pro¬ 
gram selector (you must include the quotes). The /c argument forces the 
command processor in the new screen group to end the session as soon as 
the command has terminated (command is either a program or an OS/2 
command). The final parameter, arguments , consists of the parameters that 
are passed to the command. If no command is specified, OS/2 starts the 
command interpreter in the new screen group. 

The Structure of a Protected Mode Screen Group 

Under OS/2, separate screen groups run concurrently. Furthermore, the 
individual processes (that is, programs) that belong to a screen group can 
also run concurrently. Figure 1.4 illustrates an example screen group. The 
treelike structure of this collection of processes emphasizes two important 
features: 

♦ A single process can start multiple child processes. 

$ The parent and child processes can all run concurrently (the fact 
that a parent can run concurrently with a child allows the parent 
to spawn multiple children). Alternatively, a parent process can 
remain suspended until a child process terminates. 

As an example, a text editor could run a compiler as one concurrent child 
process and a sort utility as another, and allow the user to continue editing a 
file while both of these subsidiary processes are running. See Chapter 6 for 
more information on the multitasking of processes. 

Note that one or more of the processes in a screen group can be a com¬ 
mand interpreter. The protected mode command interpreter is named 
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FIGURE 1.4: A screen group under OS/2 

CMD.EXE, and is equivalent to COMMAND.COM under MS-DOS (or 
under the real mode screen group of OS/2, as will be seen shortly). If you 
initiate a new screen group by running a specific program from the session 
manager, the command interpreter is not loaded, and when the last process 
in this group terminates, the screen group automatically ends. If, however, 
you start a screen group from the session manager by requesting a command 
prompt, or from another screen group by using the START command, then 
CMD.EXE is loaded and will remain running until you issue the operating- 
system command EXIT Thus, the following command will terminate a 
protected mode screen group and return you to the session manager: 

[C:\]exit 

(This is yet another way to activate the session manager; note, however, that 
you cannot terminate the real mode screen group in this fashion.) 

Figure 1.5 illustrates an equivalent example of a “screen group” (to use 
OS/2 terminology) under MS-DOS. (This could also be the structure of a 
real mode screen group under OS/2.) Note that unlike the treelike structure 
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(More Processes) 


FIGURE 1.5: A ",screen group” under MS-DOS 

of a screen group under OS/2, the processes running under MS-DOS (or 
the OS/2 real mode) are illustrated as a linear sequence, indicating two 
important features: 

❖ A parent can start only one child process at a time. 

♦ A parent process is suspended while the child process is running; it 
resumes running when the child returns. 

There is one more layer to the multitasking structure of OS/2. Just as a 
screen group can consist of multiple concurrent processes, a single process 
can consist of multiple concurrent threads . A thread is simply the execution 
of a series of instructions in a program. Processor time is divided among all 
active threads. Thus, several sections of a single program can run simulta¬ 
neously. For example, a spreadsheet program could have one thread read¬ 
ing data from the user, another thread performing a recalculation, a third 
thread updating a display of the time and keyboard status, and so on. Fig¬ 
ure 1.6 illustrates the structure of a protected mode process. Note that the 
process begins with the execution of a single thread. Any thread can start 
additional threads, and the process terminates when the last thread stops 
running. The topic of threads is fully discussed in Chapter 6. 



FIGURE 1.6: The structure of a protected mode process 

Figure 1.7 shows the structure of an MS-DOS process (or a real mode 
process under OS/2). In contrast to OS/2, an MS-DOS process consists of 
a single thread of execution. 

In summary, the multitasking components of OS/2 fall into a three-level 
hierarchy. All of these elements can run concurrently. 

1. Screen groups , or sessions: The OS/2 environment is composed of 
a collection of screen groups. A screen group is a set of processes 
that share a single virtual screen, keyboard, and mouse. You switch 
among these using the session manager or the Alt-Escape key. 

2. Processes : A screen group contains one or more processes. A 
process is the execution of an individual program, and can own 
resources (such as file handles and memory). You start processes 
from the session manager or by typing the name of the program 
at the command line. Processes themselves can start other (child) 
processes. 

3. Threads : A process consists of one or more threads. A thread is 
the execution of a sequence of instructions within a program, and 
processor time is shared among active threads. The user does not 
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FIGURE 1.7: The structure of a real mode process 

start individual threads; one thread is started when the program 
begins execution, and the program can then start additional 
threads. 

The Real SVSode Screen Group 

OS/2 provides a single screen group for running standard MS-DOS appli¬ 
cations in the real mode of the 80286 processor. The real mode screen group 
is also known as the compatibility box or the 3.x box (indicating its compat¬ 
ibility with MS-DOS versions 3.0 to 3.3). Installing this screen group is 
optional; you can control whether it is installed and can adjust the amount 
of memory it uses through the PROTECT ONLY and RMSIZE commands 
in the configuration file (see the section on configuration commands, 
later in the chapter). 

The purpose of the compatibility box is to provide an environment in 
which MS-DOS applications can run exactly as they run under MS-DOS, so 
that you can convert your system to OS/2 without giving up the ability to 
run the large body of MS-DOS software. These applications cannot take 
advantage of the advanced features of OS/2; the only benefit is that they 
can be loaded and run alongside applications written specifically for OS/2. 
Not all MS-DOS applications can successfully run in the compatibility box; 
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see Chapter 4 for a discussion of how to write MS-DOS applications that 
will safely run within this environment. 

You can switch into and out of the real mode screen group using the Alt- 
Escape key or the session manager, in the same manner as the protected 
mode screen groups. Figure 1.1 illustrates the relationship of the real mode 
box with the other components of the system. The command interpreter 
that loads real mode programs and executes operating-system commands is 
the familiar COMMAND.COM, Note that the START and DETACH 
commands are absent from the diagram; the abilities to start another screen 
group or begin a background program are provided only by the protected 
mode command processor, CMD.EXE, 

The compatibility box is a collection of processes that share a common 
screen, keyboard, and mouse, and therefore it fits loosely into the defini¬ 
tion of a screen group given in this chapter. However, the following are 
some important differences between this screen group and the protected 
mode screen groups: 

♦ There can be only a single real mode screen group, but there can 
be multiple protected mode screen groups. 

♦ When the real mode screen group is in the foreground, the OS/2 
protected mode screen groups continue to run. However, when 

a protected mode screen group is running in the foreground, the 
real mode screen group is suspended ; all processes in this group 
stop running. 

♦ Programs running in the real mode screen group cannot take 
advantage of multitasking, the large virtual address space, or other 
protected mode features discussed at the beginning of the chapter. 
The real mode screen group and real mode processes conform to 
the MS-DOS model illustrated in Figures 1.2, 1.5, and 1.7. 

Programs running in the real mode screen group need to be suspended 
when they are in the background because many MS-DOS applications 
bypass the operating system and directly access low-level machine features. 
For example, most high-performance MS-DOS programs produce screen 
output by writing directly to video memory. Thus, the system cannot cap¬ 
ture video output from these applications in a virtual screen; if they were 
not suspended while in the background, they would overwrite the screens 
belonging to protected mode applications. Since real mode programs are 
subject to being suspended, the compatibility box is not suitable for pro¬ 
grams incorporating interrupt service routines that must not miss incoming 
hardware interrupts, such as timer utilities or communications programs. 
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Background Programs 

Under OS/2 you can also relegate a protected mode program permanently 
to the background. These true background programs do not belong to a 
normal screen group, and are therefore illustrated in Figure 1.1 outside the 
circle of screen groups. You cannot “switch into 55 a background program 
using the Alt-Escape key or the session manager, and thus you could 
describe the collection of background tasks as a special screen group that 
cannot be brought into the foreground. Furthermore, the background tasks 
do not appear on the list of running screen groups in the session manager, 
and they do not normally interact with the user through the screen, key¬ 
board, or mouse. Once a background process has been started, it must ter¬ 
minate itself; there is no way to stop it using Ctrl-C, the session manager, or 
an operating-system command. 

As shown on Figure 1.1, there are two methods for starting a program in 
the background. First, if you are at the command line of a protected mode 
screen group, you can issue the DETACH operating-system command, 
which starts the specified program in the background and returns a process 
identification number. For example, the following line runs the SORTEXE 
program in the background: 

detach sort Cunsorted.dat >sorted.dat 

The system command DETACH has the syntax 

DETACH command [arguments] 

and starts a program running in the background. 

Once you have issued this command, the system immediately returns a 
process identification number, and the prompt reappears. You are now free 
to perform other tasks while the sort operation happily churns away in the 
background (this procedure is similar to using the & operator in UNIX). In 
this example, input and output are both redirected; you must not run an 
interactive program—one that requires I/O with the screen, keyboard, or 
mouse. Note that you could also have started the sort process in another 
screen group via the START command explained previously; however, it is 
unnecessary to start an entire screen group to run a noninteractive program. 

Second, you can place a RUN command in the configuration file, CON¬ 
FIG.SYS, which will automatically load a program and run it in the back¬ 
ground at system initialization. For example, the following line in 
CONFIG.SYS will start the program WAKEUP.EXE as a background pro¬ 
cess when the system is booted: 

RUN = C:\DEMOS\APPS\WAKEUP\WAKEUP.EXE 12:00 
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The configuration command RUN has the syntax 
RUN = [drive:]\path] % filename [arguments] 

and loads and starts a background program at system initialization. 

The second method is especially useful for running a utility that is to be 
permanently installed in the background to perform some behind-the- 
scenes task, such as a print spooler or keyboard macro facility The OS/2 
facility for running programs in the background permits you to install utili¬ 
ties that provide services similar to those offered by terminate-and-stay- 
resident (TSR) programs under MS-DOS. 

Additionally, OS/2 allows background programs (as well as programs in 
a screen group) to install a monitor , which is a routine that can intercept all 
I/O associated with the keyboard, mouse, or printer. The monitor mecha¬ 
nism allows a utility to detect a hotkey or to freely modify the intercepted 
stream of characters. Also, although background programs cannot write to 
the screen using the standard OS/2 video services, there is a special set of 
“popup” functions designed specifically to allow background programs to 
interrupt the foreground process, and to display important messages on the 
screen. Chapter 11 discusses the techniques for writing a monitor, Chapter 9 
explains the use of the popup video functions, and Chapter 4 deals with the 
general issues of writing a background program. 

An OS/2 Memory Map 

Figures 1.8 and 1.9 illustrate the layout of OS/2 in physical memory to 
show the approximate locations of the operating-system components that 
have been discussed in this chapter. As mentioned in the last section, the real 
mode screen group is an optional feature (see the description of new config¬ 
uration commands later in the chapter). Figure 1.8 gives a memory map for 
a system that is configured for protected mode screen groups only, and Fig¬ 
ure 1.9 maps memory for a system with both protected mode screen groups 
and a real mode screen group. 

The address of the top of memory in these diagrams is indicated as X 
Mb , where X stands for the number of megabytes of memory you have 
installed in the system. Many different figures are quoted as the amount of 
memory required to run OS/2. A practical lower limit is 1.5 megabytes for 
version 1.0; for the extended versions of OS/2 discussed in the next section, 
3 or more megabytes may be required. 

A notable feature of the organization of OS/2 in memory is that the pro¬ 
tected mode applications and the operating-system code itself must straddle 
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FIGURE 1.8: A memory map for a configuration with protected mode only 


the area reserved for the ROM BIOS and adapter cards (a tradition begun 
under the 8088 processor that must be maintained to preserve compatibility 
with existing hardware devices and BIOS chips). In both memory maps, the 
operating-system code is divided between a low area at the bottom of mem¬ 
ory and a high area starting at 1 megabyte. These areas of memory are 
fixed , meaning that the OS/2 memory manager is not free to move them 
around in memory. The device drivers that service both real mode and pro¬ 
tected mode applications are located in the low system area. 

The areas labeled Protected Mode Application Code and Data Segments 
are the locations of the protected mode screen groups and background pro¬ 
grams. These areas are normally movable , meaning that the memory man¬ 
ager is free to rearrange the segments in physical memory (see the section in 
Chapter 2 on virtual memory for an explanation of the virtual addressing 
scheme that enables the system to move segments in memory without 
affecting the programs using these segments). 

If you choose to install a real mode screen group, memory will be orga¬ 
nized as shown in Figure 1.9. The real mode applications are placed imme¬ 
diately above the operating-system code in low memory. The address of the 
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VERSIONS AND 
COMPATIBILITIES 



FIGURE 1.9: A memory map for a configuration with the real mode screen group 


top of the real mode area depends upon the current configuration file set¬ 
ting (see the RMSIZE configuration command in the last section of this 
chapter); you can set this upper address to a maximum value of 640 kilo¬ 
bytes. If you set the address to a lower value, then the area between the top 
of the real mode section and 640 kilobytes is not wasted—it is used to con¬ 
tain additional protected mode segments. If the real mode compatibility 
box is selected, the layout of lower memory closely emulates that of MS- 
DOS. However, the size of the low operating-system code for OS/2 is larger 
than that for MS-DOS: approximately 100 kilobytes for OS/2 and approxi¬ 
mately 50 kilobytes for MS-DOS 3.3. 


OS/2 is a multifaceted and evolving operating system. It represents a major 
advance over MS-DOS, and yet it must provide compatibility with MS- 
DOS software during its initial stages. This section will clarify some of the 
confusion engendered by the different OS/2 versions, the myriad software 
environments supported by MS-DOS and OS/2, and the variety of applica¬ 
tion types that can run in the different environments. 
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OS/2 Versions 

Even though OS/2 is a new operating system, a confusing array of versions 
are already available or planned for the future. A given version can be clas¬ 
sified according to three independent criteria: 

♦ Whether the Presentation Manager is included (version 1.0 vs. 
version 1.1) 

♦ The presence of IBM extensions (the regular edition vs. the 
extended edition) 

♦ The processor that is supported (the 80286 version vs. the 80386 
version) 

Version 1.0 vs. Version 1.1 

The difference between versions 1.0 and 1.1 is that version 1.1 includes the 
Windows Presentation Manager and version 1.0 does not. Version 1.0, the first 
release of OS/2, contains all the components of the operating system necessary 
to support text mode applications. This version is designed to allow devel¬ 
opers to quickly convert existing text mode applications from MS-DOS to the 
protected mode of OS/2. If these applications are written using the operating- 
system services and following a simple set of rules, they will also be able to run 
within a window of the Presentation Manager in version 1.1. Although you can 
write graphics applications under version 1.0 by directly accessing the video 
hardware, Microsoft strongly recommends using the Presentation Manager 
interface for all graphics programs (otherwise, these applications will not be 
able to run in a window or take advantage of the graphics interface and other 
features of the Presentation Manager). 

The Windows Presentation Manager is a windowed, multitasking pro¬ 
gram environment with a graphics interface, similar in outward appearance 
to Microsoft Windows version 2.0 and Windows 386. It features overlap¬ 
ping windows, supports enhanced interprocess communication, and 
provides an extensive set of device-independent graphics functions for 
application programs. The interface also conforms to the standard defined 
by IBM—the Systems Application Architecture (SAA). Chapter 12 intro¬ 
duces the topic of developing programs for the Presentation Manager. As 
mentioned earlier in this chapter, the Presentation Manager, and the appli¬ 
cations written for it, belong to a single protected mode screen group. Thus, 
you can have non-Windows applications running at the same time in other 
screen groups. The Presentation Manager replaces the session manager that 
was discussed in the last section with its own Task Manager. 
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The Regular Edition vs, the Extended Edition 

The extended edition of OS/2 contains operating-system extensions devel¬ 
oped by IBM. The two primary extensions are a Communications Manager 
and a Database Manager. These additions provide software developers with 
extensive built-in database and communications facilities. Several applica¬ 
tions under development by IBM and others make use of these services and 
will thus require the extended version of OS/2. 

Note that the distinction between the regular edition and the extended 
edition is independent of whether the Presentation Manager is included. 
Thus, version 1.0 and version 1.1 will be available in both a regular and an 
extended edition. 

As mentioned in the section on dynamic linking, OS/2 is an open, modu¬ 
lar operating system. There is a well documented, publicly available inter¬ 
face for attaching operating-system extensions. Therefore, the IBM 
extensions provided with the extended edition have no advantages over 
other extensions (other than IBM’s unique marketing position). Microsoft 
and other developers will also provide operating-system extensions; an 
example is the Microsoft LAN Manager. 


The 80286 Version vs. the 80386 Version 

The first versions of OS/2 are designed specifically for the Intel 80286 pro¬ 
cessor. These 286 versions will also run perfectly on the 80386 processor, but 
will not take advantage of any of its advanced features (except for the more 
efficient mode switching and higher processor speeds). However, a version 
of OS/2 is under development that will exploit the potential of the 80386. 
Among the planned enhancements are the following: 

♦ A larger total address space, and larger individual segments 

♦ Enhanced memory management (paged virtual memory) 

♦ Greater system security (for example, device I/O access will be 
regulated on a port-by-port basis) 

♦ Multiple real mode screen groups that continue to run in the back¬ 
ground 

Programs developed for the 286 versions of OS/2 should run without 
modification under the 386 versions. However, to take advantage of the 
unique features supported by the 80386, developers will need to modify 
these programs. 
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Hardware Compatibilities 

As mentioned in the first section in this chapter, OS/2 requires an 80286- or 
80386-based machine. It will run on the IBM PC AT, PC XT/286, and 
PS/2 models 50,60, and 80. It will also run on most machines that are com¬ 
patible with these models, and on many other 80286/386 systems. OS/2 
will not run on the IBM PC, PC XT, PS/2 models 25 and 30, or other 
machines that do not use the 80286 or 80386 processors. There are, how¬ 
ever, several 80286- or 80386-based accelerator cards that can be added to a 
PC or PC XT that will allow the computer to run OS/2. An example is the 
Mach 20 card from Microsoft, which uses the 80286 chip and not only sig¬ 
nificantly increases the speed of a PC, but also allows it to run OS/2. Note 
that many accelerator cards designed for the PC, even those that use the 
80286 or 80386 chip, do not support OS/2. 

Also note that OS/2 will not automatically run on every 80286 or 80386 
computer; not all machines that run MS-DOS will immediately run OS/2. 
The computer vendor may need to supply a set of custom device drivers to 
support the hardware configuration, or provide a special version of OS/2 
with adaptations. OS/2 makes extensive use of installable (and therefore 
replaceable) drivers for devices such as the screen, keyboard, printer, 
and disk drives, and therefore it can be adapted to support new hard¬ 
ware peripherals. 

Software Compatibilities 

Table 1.1 summarizes the compatibilities of different types of applications 
with the various software environments offered by MS-DOS and OS/2. 
This section summarizes these environments and application types, and 
qualifies some of the facts presented in the chart. 

Software Environments 

The software environments are listed at the top of Table 1.1. The following 
notes explain each of these environments. 

HEADING EXPLANATION 

MS-DOS 3.x This category refers to MS-DOS versions 3.0 and later. 

Most applications that run under MS-DOS 3.x will also 
run under MS-DOS 2.x. 

OS/2 3.x Box This heading refers to the real mode screen group. Note 

that Microsoft Windows 2.0 {not earlier versions) can be 
run in this environment. 




TABLE 1.1: Compatibilities of Application Types with MS-DOS and OS/2 Software Environments 
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OS/2 Protected This heading refers to any protected mode screen group 
Mode Screen not running the Presentation Manager. 

Group 


Windows 2.0 


OS/2 

Presentation 

Manager 


OS/2 386 
Protected Mode 


OS/2 Extended 
Edition Protected 
Mode 


This is the Microsoft Windows operating environment, 
version 2.0. An application type is considered to be 
compatible with Windows 2.0 if it can run within a 
window (that is, if it does not require the entire screen); 
the program need not be written specifically for 
Windows. Note that Windows 2.0 can be run under 
MS-DOS or in the real mode screen group of OS/2. 

This is the enhanced version of Microsoft Windows that 
runs in a protected mode screen group of OS/2 and is 
included with version 1.1. In the chart, compatibility 
means that the application can run within a window; it 
need not be written specifically for the Presentation 
Manager. 

This environment refers to any protected mode screen 
group (including a screen group running the Presentation 
Manager) belonging to the 80386 version of OS/2. Note 
that all other environments listed in the chart are 
assumed to belong to the 80286 version. 

This heading refers to any protected mode screen group 
(including a screen group running the Presentation 
Manager) belonging to an extended edition of OS/2. 

Note that all other environments listed in the chart are 
assumed to belong to the regular edition. 


Application Types 

The different application types are listed down the left side of Table 1.1. 

The following are explanations of each of these types. 

HEADING EXPLANATION 

MS-DOS This large category includes all current and future 

Applications MS-DOS applications. Note that not all of these 

programs will run in the OS/2 3.x box; Chapter 3 
discusses the rules for writing an MS-DOS application 
that will successfully run in the OS/2 real mode screen 
group. Note also that many MS-DOS programs cannot 
run within a window of Microsoft Windows 
2.0—specifically, those that directly manipulate video 
memory or the keyboard (these applications must be 
given control of the entire screen and cause multitasking 
to be suspended). 
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Windows 2.0 
Applications 


OS/2 Kernel 
Applications 


OS/2 Family 
API Application 


OS/2 

Presentation 

Manager 

Applications 


This category refers to applications written specifically 
for the Microsoft Windows program environment, 
version 2.0. The chart indicates that they will run under 
MS-DOS or under the 3.x box of OS/2—provided, of 
course, that Windows is installed! They will not run 
under the standard command interpreter 
(COMMAND.COM). 

These applications are written for a protected mode 
screen group of OS/2. They may call any function 
belonging to the standard application program interface 
(API), but may not use any of the unique services 
furnished by the Presentation Manager. They will, 
however, run within a window of the Presentation 
Manager provided that they access devices through the 
standard OS/2 API, and follow a simple set of rules (for 
example, no direct access to video memory). Chapter 13 
discusses the rules for writing a kernel application that 
can run in a Presentation Manager window. Microsoft 
expects that many existing MS-DOS programs will be 
quickly converted to kernel applications under OS/2, 
but that ultimately most OS/2 software will be written 
specifically for the Presentation Manager. 

This category consists of specially developed programs 
that can run under MS-DOS, in the 3.x box of OS/2, 
and in an OS/2 protected mode screen group. When 
writing such an application, you may use only a subset 
of the OS/2 API functions, and must process the 
program through a special utility. These procedures are 
discussed in Chapter 5. Note that many of the OS/2 
utilities (such as FORMAT.EXE) are family API 
applications; thus, there do not need to be separate 
versions of these programs for real and protected modes. 

These are applications written specifically for the 
Presentation Manager that make use of the special 
functions belonging to the Presentation Manager 
application programming interface. Table 1.1 indicates 
that these programs run under the 80386 version and the 
extended edition of OS/2; obviously, the Presentation 
Manager must be present. Note that even though the 
Presentation Manager user interface is similar to that of 
Windows 2.0, and programming under these two 
environments is much the same, Windows 2.0 
applications must be converted to use the new API and 
the enhanced set of graphics functions of the 
Presentation Manager. 
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NEW OS/2 
COMMANDS 


OS/2 Extended 

Edition 

Applications 


80386 

Applications 


This category refers to applications written specifically 
for the IBM Extended Editions of OS/2 that make use 
of the database and communications facilities provided 
by these versions. IBM is developing several such 
applications. 

This group consists of programs written specifically for 
the 80386 processor that make use of instructions unique 
to the 80386, such as those that manipulate 32-bit 
registers. Even if the target processor is an 80386, these 
applications cannot be run on the 80286 version of 
OS/2, since this version does not save the contents of the 
32-bit registers when switching from one task to another. 


Several new operating-system commands are provided by OS/2. As under 
MS-DOS, there are two distinct types of commands. First, there is a special 
set of commands that can be placed in the configuration file, and are exe¬ 
cuted only once when the system is initialized. The second type of com¬ 
mands may be typed at the operating-system prompt, or may be placed in a 
batch file for automatic execution of a series of commands. Both categories 
are discussed in this section. 

Before reviewing the individual commands, it is important to under¬ 
stand how the various parts of the system are initialized and begin process¬ 
ing these commands. When OS/2 is first booted, it reads and processes a 
single configuration file, which bears the same name as the MS-DOS con¬ 
figuration file: CONFIG.SYS. The configuration commands you can place 
in this file are described below. Some of these commands affect only the 
protected mode environments, some affect only the real mode screen 
group, and some affect both environments. (Note that specific names for 
the configuration file and startup batch files can vary, depending on the ver¬ 
sion of OS/2. For example, some versions provide a dual-boot option that 
allows you to boot either OS/2 or MS-DOS from the same hard disk vol¬ 
ume; in this case, the initialization files use a different naming scheme to 
distinguish the MS-DOS files from the OS/2 files. See the user’s guide sup¬ 
plied with your version of OS/2 for details.) 

Subsequently, OS/2 looks for a file by the name of STARTUP.CMD in 
the root directory of the boot disk. If it finds this file, it starts an initial pro¬ 
tected mode screen group and automatically executes the commands the file 
contains. If this file is not found, then OS/2 runs the session manager with¬ 
out starting a protected mode screen group. The STARTUP.CMD batch file 
is similar to AUTOEXEC.BAT under MS-DOS; in the protected mode of 
OS/2, all batch files have the extension .CMD rather than .BAT. Note that 
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STARTUP.CMD is executed only for the first protected mode screen group-, 
also, any environmental variables you assign in STARTUP.CMD through 
the SET, PATH, and PROMPT commands are valid only for this initial 
screen group. (Each screen group under OS/2 has a distinct set of environ¬ 
ment variables, and its own current directory.) 

When subsequent screen groups are started, OS/2 will execute a com¬ 
mand file named OS2INIT.CMD, which should be in the root directory of 
the boot disk. (Note that you can substitute another directory or command 
file through the PROTSHELL configuration command, described later in 
the chapter.) If you want the initial protected mode screen group to have the 
same environment settings as all other protected mode screen groups, place 
the single command 

os2init 

in the STARTUP.CMD file. Then place all commands required to establish 
the environments in the file OS2INIT.CMD. 

After STARTUP.CMD is processed, the command prompt appears, 
and the protected mode command interpreter, CMD.EXE, is ready to 
load protected mode programs or perform operating-system commands. 
The protected mode operating-system commands you may place in a 
.CMD batch file, or execute from the protected mode command line, are 
discussed below. 

When OS/2 starts the real mode screen group, it looks for a file named 
AUTOEXEC.BAT in the root directory of the boot disk; just as under 
MS-DOS, if it finds this file, it automatically executes the commands it 
contains. Once this file is processed, the real mode command prompt 
appears, and the real mode command interpreter, COMMAND.COM, 
is ready to load MS-DOS-compatible programs and execute operating- 
system commands. The real mode operating-system commands that can 
be placed in a .BAT batch file, or typed at the real mode command prompt, 
are discused below. 

Note that OS/2 provides a menu-driven program called INSTAID to 
help you prepare the hard disk, create appropriate directories, copy the sys¬ 
tem files to the hard disk, and prepare the four special files CONFIG.SYS, 
STARTUP.CMD, OS2INIT.CMD, and AUTOEXEC.BAT. 

Configuration Commands 

The OS/2 commands that can be placed in the CONFIG.SYS file to modify 
the default configuration settings used by the system are summarized 
below. For each command, the description states which operating modes— 
real or protected—are affected by the command, and whether the com¬ 
mand is also supported by MS-DOS or is unique to OS/2. See one of the 
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many reference guides to MS-DOS, or the OS/2 user’s guide, for a descrip¬ 
tion of the commands that are the same as those provided by MS-DOS. 

Note that the following configuration commands provided by MS-DOS 
are not supported by OS/2: 

❖ FILES (under OS/2, the number of file handles can grow dynami¬ 
cally as needed) 

❖ LASTDRIVE 

❖ STACKS 

See the OS/2 user’s guide for more details on the commands unique to 
OS/2. Several new OS/2 commands allow you to fine-tune the mechanisms 
used by the system for multitasking and memory management, and you can 
adjust them to achieve optimal performance for various types of applica¬ 
tion programs. 

BREAK (Real Mode) 

BREAK is also an MS-DOS command. It sets the status of Control-C 
checking. 

BUFFERS (Rea! and Protected Modes) 

BUFFERS is also an MS-DOS command. It specifies the number of buffers 
OS/2 allocates for disk I/O. The allowable range is from 4 to 99, and the 
default value under OS/2 depends on your hardware configuration. 

CODEPAGE (Rea! and Protected Modes) 

The CODEPAGE command is unique to OS/2. It selects the code pages 
that the operating system will create for code-page switching. Code 
pages define character sets for various nationalities that are displayed by the 
monitor or printer. Code-page switching is also supported by PC-DOS 3.3. 
See the descriptions of the CODEPAGE and DEVINFO commands in the 
OS/2 user’s guide for information on code pages. 

COUNTRY (Real and Protected Modes) 

COUNTRY is also an MS-DOS command. It causes the operating system 
to use the date, time, and currency conventions of a specified country or 
language. 
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DEVICE (Real and Protected Modes) 

DEVICE is also an MS-DOS command. It allows you to install optional 
device drivers. See the sections on the structure of OS/2 and OS/2 device 
drivers in Chapter 2 for more information on the available device drivers. 


DEVINFO (Real and Protected Modes) 

The DEVINFO command is unique to OS/2. It prepares a specific device 
for code switching. See the descriptions of the CODEPAGE and DEVINFO 
commands in the OS/2 user’s guide for information on code pages. 

DISKCACHE (Real and Protected Modes) 

The DISKCACHE command is unique to OS/2. It causes OS/2 to set up a 
disk cache to improve the efficiency of disk I/O. The syntax is 

DISKCACHE = n 

where n specifies the size of the cache in kilobytes. 

FCBS (Real Mode) 

FCBS is also an MS-DOS command. It specifies the number of file control 
blocks that can be open concurrently (the OS/2 default is 16), and the num¬ 
ber of files protected against automatic closure (the OS/2 default is 8). Note 
that the defaults for these two values under MS-DOS are 4 and 0. 


IOPL (Protected Mode) 

The IOPL command is unique to OS/2. It grants low-level 1/O privilege to 
processes that request it. See the sections on privilege and restricted instruc¬ 
tions in Chapter 2. To allow I/O privilege, enter 

IOPL = YES 

and to disallow it, enter 
IOPL = NO 

The default is IOPL = YES. 

LIBPATH (Protected Mode) 

The LIBPATH command is unique to OS/2. It specifies the location of the 
dynamic-link libraries. The command allows you to specify several paths, 
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which will be searched in order, and has the following syntax: 

LIBPATH = drive:path[;drive:path ][...] 

The default is the root directory of the boot disk. 

MAXWAIT (Protected Mode) 

The MAXWAIT command is unique to OS/2. It specifies the maximum 
time that a thread must wait before its priority may be temporarily 
increased (for one time slice). The purpose of this command is to limit the 
amount of time any active thread waits before running. The syntax is 

MAXWAIT = X 

where x is the maximum waiting period in seconds, ranging from 1 to 255 
(default: 3 seconds). This command has no effect if the PRIORITY com¬ 
mand is set to ABSOLUTE. See the description of multitasking and priori¬ 
ties in Chapter 6. 

MEMMAN (Protected Mode) 

The MEMMAN command is unique to OS/2. It sets the memory manage¬ 
ment options. The following three combinations of options may be speci¬ 
fied with this command: 

MEMMAN = NOSWAP,NOMOVE 


or 


MEMMAN = SWAP,MOVE 
or 


MEMMAN - NOSWAP,MOVE 

The SWAP and NOSWAP options enable and disable swapping of code 
and data segments between memory and a disk. The swapping mechanism 
allows the system to maintain the large virtual address space mentioned pre¬ 
viously in the chapter; however, for time-critical applications, response time 
can be improved by disabling swapping. The MOVE and NOMOVE 
options dictate whether segments can be relocated in memory; again, time- 
critical applications may require disabling of segment moving. Note that 
the SWAP option automatically enables the MOVE option. 

The default value is MEMMAN = SWAP,MOVE if the system is booted 
from a hard disk, and MEMMAN = NOSWAP,MOVE if the system is 
booted from a floppy disk. 
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PAUSEONERROR (Real and Protected Modes) 

The PAUSEONERROR command is unique to OS/2. It determines 
whether the system will pause and display an error message if it encounters 
an error in the CONFIG.SYS file. The syntax is 

PAUSEONERROR = YES 

which is the default, or 

PAUSEONERROR = NO 

PRIORITY (Protected Mode) 

The PRIORITY command is unique to OS/2. It modifies the mechanism 
used by the system to schedule threads. There are two possible values: 

PRIORITY = ABSOLUTE 

forces the system to schedule all active threads strictly on a first-come, first- 
served basis. 

PRIORITY = DYNAMIC 

which is the default value, allows the system to temporarily adjust the rela¬ 
tive priorities of active threads to minimize the amount of time any thread 
must wait to receive processor cycles. If this command is set to ABSO¬ 
LUTE, the MAXWAIT command will have no effect. See the description 
of multitasking and priorities in Chapter 6. 

PROTECTONLY (Real and Protected Modes) 

The PROTECTONLY command is unique to OS/2. It controls whether the 
system creates a real mode screen group. There are two possible values: 

PROTECTONLY = YES 

eliminates the real mode screen group, so that you can run only protected 
mode applications. 

PROTECTONLY = NO 

which is the default value, causes the system to set up a real mode screen 
group, so that you can run both MS-DOS-compatible programs as well as 
protected mode OS/2 applications. 

PROTSHELL (Protected Mode) 

The PROTSHELL command is unique to OS/2. It specifies the program 
selector (session manager) and the protected mode command interpreter. 
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The syntax is 

PROTSHELL =progsel [cmdint [args 1 ]] 

where progsel is the full path name of the desired program selector (the 
OS/2 default is SHELL.EXE), cmdint is the full path name of the desired 
protected mode command interpreter (the OS/2 default is CMD.EXE), 
and args are optional arguments to be passed to the command interpreter. 
For example, the line 

protshell = c:\os2\pbin\shell.exe c:\os2\pbin\cmd.exe /k 
c:\os2init.cmd 

specifies the default command interpreter and the default program selector, 
both located in the C:\OS2\PBIN directory. This command also specifies 
that each time CMD.EXE is loaded it will remain permanently in memory 
(the /k option) and automatically run the batch file OS2INIT.CMD. 

REM (Rea! and Protected Modes) 

The REM command is unique to OS/2. Any line in CONFIG.SYS that 
begins with the REM statement is treated as a comment and is not processed 
as part of the file. The syntax is 

REM text 

where text is a remark. 

RMSIZE (Real and Protected Modes) 

The RMSIZE command is unique to OS/2. It determines the amount of mem¬ 
ory the system will reserve for the real mode screen group. The syntax is 

RMSIZE = x 

where * is a value between 0 and 640 kilobytes. As illustrated in Figure 1.9, a 
portion of this memory is used by the lower section of the operating system, 
and is therefore not available to real mode applications. 

The default value depends upon the total amount of memory installed in 
the system. Note that the command PROTECTONLY must be set to NO in 
order to reserve memory for real mode programs. 

RUN (Protected Mode) 

The RUN command is unique to OS/2. It is used to load and run a background 
program at system initialization. The RUN command was described earlier in 
this chapter, in the section on background programs. 
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SHELL (Red Mode) 

SHELL is also an MS-DOS command. It specifies the real mode command 
processor (the default is COMMAND.COM). 


SWAPPATH (Protected Mode) 

The SWAPPATH command is unique to OS/2. It specifies the location of 
the swap file on disk. The swap file is the temporary repository of the seg¬ 
ments that are swapped out of memory. The presence of a swap file enables 
the OS/2 memory manager to maintain the large address space described 
previously in the chapter. Note that the SWAP option of the MEMMAN 
configuration command must be selected to enable swapping. Also, the 
swap file should be located on a hard disk. The syntax of this command is 

SWAPPATH = drive : [path] 

The default location of the swap file is the root directory of drive C. 


THREADS (Protected Mode) 

The THREADS command is unique to OS/2. It specifies the maximum 
allowable number of threads. The syntax is 

THREADS =x 

where x is the desired maximum number of threads, and is a value ranging 
from 16 to 255 (the default depends on your hardware configuration). See 
the discussion of threads in the section on the structure of a protected mode 
screen group, earlier in this chapter. 


TIMESLICE (Protected Mode) 

The TIMESLICE command is unique to OS/2. It sets the minimum and 
maximum periods of time that an individual thread is allowed to run each 
time it is scheduled by the OS/2 dispatcher. The syntax is 

TIMESLICE = x[,y\ 

where x is the minimum time in milliseconds, and y is the maximum time in 
milliseconds. The smallest minimum time that may be specified is 32; if only 
a single number is given, the minimum and maximum will both be assigned 
this value. See the discussion of threads in the section on the structure of a 
protected mode screen group, earlier in this chapter. 
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TRACE and TRACEBUF 

Note that there are two additional configuration commands, TRACE and 
TRACEBUF, that apply only to a special version of the kernel that is sup¬ 
plied with the OS/2 Software Development Kit. 


Command Line and Batch Commands 

This section summarizes the new commands provided by the OS/2 com¬ 
mand processors. These commands can be executed from the command 
line, or placed in batch files to execute a sequence of commands. The com¬ 
mands provided by the real mode command interpreter are treated sepa¬ 
rately from those provided by the protected mode command interpreter. 


Real Mode Commands 

The real mode commands are those that can be issued from the command 
line of the real mode screen group, or placed in batch files (with the .BAT 
extension) for the automatic execution of a sequence of commands. These 
commands are executed by the real mode command processor, COM¬ 
MAND. COM. In general, the set of OS/2 real mode commands is the same 
as that provided by MS-DOS; there are, however, two exceptions. First, the 
following commands available under MS-DOS version 3.3 are not sup¬ 
ported by OS/2: 

CTTY 

FILCOM 

NLSFUNC 

SELECT 

SHARE 

Although the MS-DOS 3.3 NLSFUNC command is not provided by OS/2, 
code pages can be selected with the new configuration command, CODE- 
PAGE. Also, the MS-DOS SELECT command for installing the system 
onto a disk is replaced in OS/2 by an installation diskette. Finally, the net¬ 
work file-sharing support that is loaded by means of the SHARE command 
under MS-DOS is automatically included in OS/2. 

Second, there are three commands available in the real mode of OS/2 
that are not found in MS-DOS 3.3: HELPMSG, PATCH, and SET- 
COM40. These commands perform the following functions. 
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HELPMSG (HELP) The HELPMSG command provides complete explana¬ 
tions for system errors. The syntax is 

HELPMSG messageid 


or 


HELP messageid 

where messageid is the identifier returned by the system when an error 
occurs. You can also display or remove the help line at the top of the screen 
by typing 

HELP ON 

or 

HELP OFF 

Typing HELPMSG or HELP by itself provides a summary of the options. 

PATCH The PATCH command allows you to make changes to program 
code. The syntax is 

PATCH [[drive:]path][/ a] 

where the specified path is that of the executable program that you want to 
modify. The PATCH command will normally prompt you for the offset and 
modified contents; if you use the /a option, however, the specified path will 
be that of a file that contains the information necessary to automatically 
patch one or more files. 

8ETCOM40 The SETCOM40 command makes a specified serial port avail¬ 
able to a real mode program. It has the syntax 

SETCOM40 COM* = ON 

or 

SETCOM40 COM* = OFF 

where * is the desired serial port, and is a value from 1 to 8. 

For a description of the other real mode commands, see a handbook cov¬ 
ering MS-DOS version 3.3, or the OS/2 user’s guide. 


Protected Mode Commands 

The protected mode commands are those that can be issued from the com¬ 
mand line of a protected mode screen group, or placed in a batch file with 
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the .CMD extension. These commands are executed by the protected mode 
command processor, CMD.EXE. 

All of the commands available in the real mode are also available in the 
protected mode, except for the following commands that are supported by 
the real mode only: 

APPEND 

ASSIGN 

BREAK 

COMMAND 

GRAFTABL 

JOIN 

SETCOM40 

Additionally, there are several commands that are available in the pro¬ 
tected mode only. These commands are as follows. 

ANSI The ANSI command determines whether the protected mode of OS/2 
supports ANSI escape sequences in screen output. The syntax is 

ANSI [ON] 

or 

ANSI [OFF] 

The ON option causes OS/2 to respond to ANSI escape sequences embed¬ 
ded in screen output to move the cursor and perform other video control 
functions. To achieve ANSI support for the real mode, you must include 
the line 

DEVICE = ANSI. SYS 

in the configuration file. The OFF option causes OS/2 to treat ANSI sequences 
as normal characters. If you type the ANSI command with no arguments, the 
system returns the current status of ANSI support —on or off. 

The default status is ON. 

CMD The CMD command loads a secondary copy of the protected mode 
command processor. The syntax is 

CMD [drive:][path] [/c command(s)] 


or 


CMD [drive:]\path] [/k [command(s)]] 
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where path is the location of the copy of CMD.EXE to load, and com- 
mand(s) specifies the command or commands you want the command pro¬ 
cessor to execute. The two switches have the following meanings: 

/c This option causes the secondary command processor to perform the 
command, and then immediately exit to the primary command 
processor. 

/k This option forces the secondary command processor to remain in 
control after the command is executed. To return to the primary 
command processor, you must issue the EXIT instruction. 

DETACH The DETACH command starts an application running in a new 
screen group. It was described in the section on background programs, ear¬ 
lier in the chapter. 

DPAIH The DEATH command specifies the directories that are to be 
searched for data files (that is, all files that do not have the extensions 
.COM, .EXE, or .CMD). The syntax is 

DEATH [ drive:]path[ ; [drive\path ...] 

One or more search paths may be specified; multiple paths must be sepa¬ 
rated by semicolons. If the DEATH command is given with only a single 
semicolon (DEATH ;), then all previous path settings are cleared; if the 
command is given with no parameters, then the system displays the current 
data file search paths. When looking for a data file, the system will first 
search the current or specified directory; it will then search the directories 
given by DEATH. This command is similar to the real mode AEEEND 
command. Note that DEATH affects only the screen group from which 
it is issued. 

ENDLOCAL The ENDLOCAL command is for use in batch files. It restores 
the drive, directory, and environment settings that were in effect before the 
SETLOCAL command was issued. 

EXTPROC The EXTEROC command is for use in batch files. It specifies a 
command processor that is to be used for the execution of the batch file. Its 
syntax is 

EXTPROC [filename] [arguments] 

where filename is the name of the batch processor, and arguments gives any 
parameters you want to pass to the new processor. The line must be the first 
in the batch file; the new processor will remain in control only while the 
batch file is being executed. 



Programmer’s 
Guide to OS/2 
CHI 


SETLOCAL SETLOCAL is a special command for batch files that allows 
you to define local values for the current drive, current directory, and envi¬ 
ronment variables. When the SETLOCAL command is issued, the existing 
settings for these values are saved. You may then change the drive and direc¬ 
tory, or redefine environment variables (with the SET command, for 
example). These new values will remain in effect only until the END- 
LOCAL command is given or the batch file ends; at this point the original 
settings saved by SETLOCAL are restored. Note that any new environment 
variables defined after the SETLOCAL command will persist after the 
batch file terminates, since there are no saved values for these variables to 
be restored. 

SPOOL The SPOOL command starts the OS/2 print spooler, which prints 
files in the background while other programs are running. The syntax is 

SPOOL [drive:][path\ [/d'.devicel] [/o\device2) 

where drive and path specify the directory where the temporary spool files 
are to be stored. The /d option specifies a parallel printer device (LPT1, 
LPT2, and so on; LPT1 is the default). All output to this device from an 
application program will be rerouted to the spooler instead of to the device. 

The /o option specifies the physical device to receive the output from the 
spooler. By default, OS/2 uses the same device given in the /d option. 
Unlike the /d option, the /o option can specify either a parallel or a serial 
device. 

The default spool directory is \SPOOL. 

START The START command is used to start a process running in another 
screen group. It was described in the section on protected mode screen 
groups, earlier in this chapter. 


Other Protected Mode Command Features 

In addition to the new commands available in the protected mode of OS/2, 
the protected mode command interpreter also provides several new general 
features that increase the power and flexibility of the command language. 

First, several traditional commands that take a single argument under 
MS-DOS and the real mode of OS/2, now take multiple arguments under 
the OS/2 protected mode. These commands are DEL, DIR, MKDIR, 
RMDIR, TYPE, and VOL. 

Second, under the protected mode you can group multiple commands on 
a single line by using the && (and), "(or), and & operators. When two com¬ 
mands are connected with the && operator, the command on the left is exe¬ 
cuted, and if this command is successful, the command on the right is 
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executed. When two commands are connected with the || operator, the com¬ 
mand on the left is executed; if this command is unsuccessful, the command 
on the right is executed; if the command is successful, the command on the 
right is not executed. When two commands are connected with the & opera¬ 
tor, both commands are always executed in order from left to right. 

Third, the OS/2 protected mode offers a richer syntax for redirecting 
input and output when running a program. The primary enhancement is 
that you can redirect the I/O from any of the first ten file handles rather 
than just standard input and standard output. See the OS/2 Programmer's 
Guide for details on this mechanism. 

Finally, the order of execution of the various operators and commands 
can be altered by using the () grouping operators. Also, the caret ( A ) serves 
as an escape symbol (similar to the \ under UNIX) that restores literal 
meaning to any of the special symbols such as > and &. For example, the 
output of the line 

echo A >hello 

would be 

>hello 

(rather than causing the output to be redirected to a file by the name 
HELLO). See the OS/2 User's Reference for a complete description of all 
the command line operators and their order of precedence. 




CHAPTER 


Programming 
under OS/2 

OS/2 is not simply an enhanced version of MS-DOS that could be 
described by presenting a short list of additional features. Rather, it is 
a radically new system. Learning to program under OS/2 requires 
understanding a set of fundamental new concepts. This chapter intro¬ 
duces these new concepts as a basis for comprehending the details of 
the programming interface, and provides a brief overview of topics 
that will be treated in detail later in the book. 

Chapter 1 explores the new features and the structure of OS/2 from 
the perspective of the user or installer of the system; this chapter, how¬ 
ever, treats these subjects from the viewpoint of the programmer. The 
final section continues the discussion of the structure of OS/2 by foc¬ 
using on the lowest level of this structure: the installable device drivers 
that form the interface between the operating-system kernel and the 
underlying hardware. 
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WHAT'S MEW 
IN OS/2 FOR 
THE 

PROGRAMMER 

♦ The application program interface 

♦ Dynamic linking 

$ Multitasking and interprocess communication 

♦ Virtual memory 

♦ Privilege 

♦ 80286 instructions 

♦ Program entry conditions 

Note that the programming features treated in this section apply to OS/2 
programs that run in a protected mode screen group. The real mode screen 
group provides an environment almost identical to MS-DOS; Chapter 3 
describes the basic features of this screen group and offers guidelines for 
writing applications that will run under the real mode of OS/2. 

Underlying the many specific differences between programming under MS- 
DOS and under OS/2 that are discussed in this section is a significant concep¬ 
tual difference. Under the MS-DOS programming model, one process at a time 
is given almost complete control of the computer resources. The programmer is 
free to manipulate virtually any element in the computer system; however, there 
is little support for introducing additional simultaneous processes. Under the 
OS/2 programming model, multiple simultaneous processes share the com¬ 
puter resources. Accordingly, the programmer must abide by a set of restric¬ 
tions that allow the operating system to regulate these processes so that they can 
interact predictably and productively. 

There is an important corollary to this basic difference in programming 
model between MS-DOS and OS/2. Under MS-DOS, the skillful program¬ 
mer generally circumvents the operating system to gain greater control and 
higher performance. Under OS/2, however, the developer must program 
under the operating system and follow its rules. In exchange for this curtail¬ 
ment of freedom, however, OS/2 offers a richer set of application services, 
a higher level of performance, and a greater degree of device independence 
than MS-DOS. For example, under OS/2 you should avoid generating 
screen output by writing directly to video memory; however, the video serv¬ 
ices offered by the operating system are many times faster and more power¬ 
ful than those provided by MS-DOS. With OS/2 it is important to program 


This section introduces the most important new features of OS/2 for the 
applications programmer, emphasizing the differences between the pro¬ 
gramming interfaces of OS/2 and MS-DOS. The specific topics are 
as follows: 
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intimately with the operating system, and to closely understand its work¬ 
ings. This section summarizes the primary ways that an application pro¬ 
grammer interacts with OS/2. 

As mentioned in Chapter 1, OS/2 is based upon the 80286 (and 80386) 
processor. Many of the enhanced features of OS/2, as well as the restric¬ 
tions to the application programmer, stem directly from the hardware fea¬ 
tures of the 80286 protected mode. This section will briefly discuss aspects 
of the 80286 architecture that underlie important features of the operating 
system. For more information on the hardware basis for OS/2, see one of 
the books on the 80286 architecture listed in the Bibliography. 

The Application Program interface 

MS-DOS and OS/2 both provide services for application programs. If you 
program in a high-level language such as C, you may not be aware of invok¬ 
ing operating-system services; however, commonly used library functions 
such as printf for writing to the screen, and read for reading a file, ulti¬ 
mately accomplish their purposes by transferring control to the operating 
system. The collection of services offered by OS/2, known as the applica¬ 
tion program interface (API), is much more comprehensive than that 
offered by MS-DOS. MS-DOS supplies approximately 100 service calls, 
many of which are redundant. The OS/2 kernel, however, offers approxi¬ 
mately 200 basic services; extensions to the operating system, such as the 
Presentation Manager and the modules of the OS/2 extended edition, sup¬ 
ply several times this number of additional services. Applications running 
under a complex multitasking system such as OS/2 have a greater need for 
operating-system-supervised services for managing multiple processes, ini¬ 
tiating interprocess communication, accessing shared peripheral devices, 
and managing segments of memory. Also, as emphasized in the introduc¬ 
tion to this section, in a multitasking system it is critical that programs 
access system resources through the operating system rather than through 
low-level code within the application itself (as is common under MS-DOS). 
Consequently, the operating system is solely responsible for providing many 
of the requirements of application programs. The API is described in Part 
Four of this book. 

The following are three important differences between OS/2 and MS- 
DOS in the manner in which operating-system services are accessed: 

<$> Under MS-DOS, operating system services are accessed through an 
interrupt instruction, primarily interrupt 21h (INT 21h), where 
each service is identified by number. OS/2 services, however, are 
accessed through a CALL instruction, where each service is identi¬ 
fied by name. 
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♦ MS-DOS services receive parameters and return values through 
machine registers . OS/2 services, however, receive parameters on 
the stack , and return values by modifying memory locations 
pointed to by address parameters. OS/2 thus uses the standard 
parameter-passing mechanism employed by high-level languages. 

$ MS-DOS services employ a motley collection of schemes for 
returning the error status. OS/2 services, however, uniformly 
return the error status in register AX, and do not use this register 
for returning other values. In a high-level language, the error sta¬ 
tus is returned directly by the function. 

As an example of the MS-DOS function-calling protocol, the following 
assembly language instructions invoke the MS-DOS service for obtaining 
the current drive: 

CurrDrive db ? ;Stores drive number. 

movah, 19h ;Loads function number into AH. 

int 21 h ;Invokes operating system, 

mov CurrDrive, al ;Saves drive number. 

Note that the single parameter (the function number, 19h) is passed in regis¬ 
ter AH, and the number for the current drive is returned in register AL 
(0 indicates drive A, 1 drive B, and so on). This same MS-DOS service could 
be accessed from C as follows: 

union REGS regs; 
unsigned char CurrDrive; 

regs.h.ah = 0x19; /* Load value for AX into structure. */ 

intdos (&regs,&regs); /* Call interface routine. */ 

CurrDrive = regs.h.al; /* Save drive number. */ 

These examples illustrate that invoking an MS-DOS service from assem¬ 
bly language is straightforward, but that invoking the same service from C 
is relatively complex. In C, register values must be loaded and unloaded 
into a structure, and then a separate assembly language function (intdos) 
must be called to transfer the values into the actual registers and issue the 
interrupt machine instruction. Accordingly, under MS-DOS most high- 
level language programs rely primarily on the services of the compiler 
library, and seldom access the operating system directly. 

Under OS/2, however, the situation is the reverse. Because OS/2 uses 
the same call-based interface employed by high-level languages, it is simpler 
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to call OS/2 services from a high-level language than from assembly lan¬ 
guage. Using assembly language necessitates pushing each parameter on the 
stack before calling the function; furthermore, parameters that supply 
address values require pushing both a segment selector and an offset (in the 
correct order!). Calling an OS/2 service from a high-level language, how¬ 
ever, is no more complex than issuing a standard function call to a library 
routine. Thus, the collection of functions offered by the standard compiler 
library is vastly expanded to include the efficient and powerful services of 
the operating system. When programming under OS/2 in a high-level lan¬ 
guage, you often have a choice between calling the operating system 
directly, using a service such as DosRead, or calling a standard library func¬ 
tion such as read, which acts as an intermediary and ultimately calls the 
operating system itself. The advantage of making direct calls is greater effi¬ 
ciency; also, the operating system offers many useful services not provided 
by a typical compiler library. The advantage of using standard library func¬ 
tions is that your C program can be more easily ported to other operating 
systems. 

The following lines of code illustrate calling an OS/2 service from the C 
language. These instructions call the OS/2 service that returns the current 
drive. 

unsigned int DriveNumber; 
unsigned long LogicalDriveMap; 
unsigned int Error; 

Error = DosQCurDisk (&DriveNumber,&LogicalDriveMap); 

The service DosQCurDisk is equivalent to the MS-DOS service illus¬ 
trated above, except that it also returns a complete mapping of all logical 
drives in the system. Note that the OS/2 service is called by name directly 
from the C program, without the need for an intermediate function call to 
issue an interrupt instruction, and that the parameters are passed directly to 
the operating system through a standard parameter list (the compiler auto¬ 
matically generates the code to push these parameters correctly onto the 
stack). 

Note also that the error status is returned directly by the function. 
Almost all OS/2 services assign the error status to register AX, and the 
value that a subroutine places in AX is the value that is returned to the call¬ 
ing high-level language program. The return type of OS/2 functions within 
a C program is unsigned int. For all OS/2 services, if the return value is 0 
then the function was successful; otherwise, the return value is a code indi¬ 
cating the specific error. All error codes refer to a single, standard list of 
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possible errors. (See Appendix D for a list of these error codes and their 
meanings.) 

OS/2 returns values other than error codes by writing directly to vari¬ 
ables located within your program; you must pass the addresses of such 
variables to OS/2. Therefore, for a service that returns values to your pro¬ 
gram, you must first define variables of the appropriate type (thereby 
reserving memory space), and then pass the addresses of these variables to 
the operating-system service. In the example above, the number of the cur¬ 
rent logged disk is assigned directly to DriveNiimber (1 indicates drive A, 2 
drive B, and so on), and a mapping of all logical drives is assigned to 
LogiealDriveMap (see the OS/2 Programmer's Reference for an explana¬ 
tion of the drive mapping). 

Another important feature of the OS/2 API is that operating system 
functions conform to the following Pascal conventions: 

♦ Parameters must be pushed on the stack in the same order that 
they are listed in the parameter list (by default in C, they are 
pushed in the opposite order). 

♦ The function must remove the parameters from the stack (the 
default in C is for the calling program to remove all parameters 
from the stack). 

♦ Each function has a fixed number of parameters (this is a result of 
the first two features; a default C function can accept a variable 
number of parameters). 

♦ The function name is converted to uppercase before being placed 
in the object file (by default, C preserves the case of function 
names and places an underscore at the beginning of the name). 

You can force a C program to follow these Pascal conventions for a spe¬ 
cific function by declaring the function with the pascal keyword. The easi¬ 
est way to correctly declare the OS/2 functions called by your program is to 
simply include the appropriate header file. Microsoft OS/2 compilers (such 
as C version 5.1) and the MS-OS/2 Programmer's Toolkit supply several 
header files containing function prototypes for the OS/2 API, as well as 
macros and definitions for constants, data types, and structures that can be 
used for calling OS/2 functions. The only header file you need to include in 
your program is OS2.H, which contains include statements for the other 
OS/2 header files. Not all of the information, however, is automatically 
included; rather, portions of the header files are selectively included 
depending upon whether certain constants are defined. If you simply 
include OS2.H without defining any of the special constants, then only the 
most commonly used information is actually included in your program. To 
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force the inclusion of additional OS/2 information, you must define one or 
more of a special set of constants before including OS2.H. For example, to 
obtain definitions for all of the functions that manage files, you must define 
the constant INCL_DOSFILEMGR, as follows: 

#define INCLJDOSFILEMGR 
include (OS2.H) 

You will see many similar examples for including the appropriate defini¬ 
tions in the programs throughout this book. For a complete list of the spe¬ 
cial constants and the information they cause the compiler to include, see 
the documentation that accompanies your compiler or the Programmer’s 
Toolkit. 

There are several important reasons for declaring an OS/2 function 
before it is called, and supplying the types of all parameters in this declara¬ 
tion. First, the compiler can check the number and types of the parameters 
in all subsequent function calls, and warn you if there are any mismatches. 
Second, address parameters passed to OS/2 are far (that is, they include 
both a two-byte segment and a two-byte offset); if you declare parameter 
types, the compiler will automatically convert all near addresses (those that 
include only a two-byte offset and are the default for the small code model) 
to far addresses. Third, all OS/2 functions themselves are far (that is, they 
are located in another code segment); the declaration will enable the com¬ 
piler to generate an appropriate far CALL instruction. Finally, the declara¬ 
tion is necessary to force the compiler to use the Pascal conventions listed 
above. If you forget to declare an OS/2 function, the first indication that 
something is terribly wrong will come from the linker. The linker will report 
the function identifier as an unresolved reference , since the compiler has 
added an underscore to the beginning of the name, which does not match 
the name in the OS/2 object file (which, following the Pascal convention, 
does not have a leading underscore). 

The OS/2 Programmer's Reference , supplied with the Microsoft Pro¬ 
grammer’s Toolkit, documents all of the OS/2 API functions in alphabeti¬ 
cal order. The definitions are given in the C language syntax. The data types 
of the functions and parameters, however, follow the Microsoft naming 
conventions, and the actual C data types are typically buried under several 
layers of type definitions. For example, the Programmer's Reference pro¬ 
vides the following definition for the DosQFilelnfo function: 

USHORT DosQFileInfo(hf,usInfoLevel,pfstsInfo,cbInfoBuf) 

HFILE hf; 

USHORT usInfoLevel; 

PFILESTATUS pfstslnfo; 

USHORT cblnfoBuf; 
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The meanings and lengths of these data types are far from obvious to a C 
programmer. Therefore, as an alternative reference for C programmers who 
feel more comfortable declaring and using standard C types, Appendix B 
defines all of the API functions using the corresponding basic C data types. For 
example, Appendix B defines this same function as follows: 

unsigned int pascal far DosQFilelnfo 
(unsigned short FileHandle, 
unsigned int InfoLevel, 

FILESTATUS far *PtrFileStatus, 
unsigned int InfoBufferLength); 

The only nonstandard C type in this definition is FILESTATUS, which is 
a structure defined in an OS/2 header file specifically to contain and access 
the information returned by DosQFilelnfo. In general, Appendix B refer¬ 
ences the structures declared in OS/2 header files, since it is easier to use one 
of these structure types (which can be quite long) than to define your own. 
Note that the program examples in this book also use standard C data types 
whenever possible to make the code easier to understand on first inspection. 

Figure 2.1 demonstrates calling the OS/2 DosQCurDisk function 
in a short C program. You can compile and link this program using the 


/* 

Figure 2.1 

This program demonstrates calling an OS/2 service from a C program. 
Prepare the program using the following command lines 
cl /G2 /Zp /Lp fig2_l.c 

*/ 

#include <os2.h> 

#include <stdio.h> 

#include <process.h> 

unsigned int DriveNumber; 
unsigned long LogicalDriveMap; 
unsigned int Error; 

void main () 

{ 

if ((Error = DosQCurDisk (&DriveNumber,&LogicalDriveMap)) != 0) 

printf ("Error number %d\n". Error); 
exit (1); 

printf ("Current drive is %c\n",64+DriveNumber); 

> /* end main */ 


FIGURE 2.1: A Cprogram that calls an OS/2 service 
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following instructions from a protected mode command line (this com¬ 
mand uses the protected mode Microsoft C compiler; the switches will be 
explained in Chapter 4). 

cl /G2 /Zp/Lp fig2_1.c 

Dynamic Linking 

Since the OS/2 operating-system functions are accessed through the stan¬ 
dard high-level call mechanism, this might seem to imply that the actual 
code for the operating-system services would have to be physically linked 
into the executable program file. OS/2, however, supports a radically new 
mechanism, known as dynamic linking , that can be used not only for 
operating-system services but also for any libraries of routines that are 
properly processed. 

Under MS-DOS, the target code for all call instructions must be bound 
into the program file by the linker; if the linker is unable to find this code, it 
reports an unresolved external reference . Figure 2.2 illustrates the typical 
linking procedure for an MS-DOS application that calls routines belonging 
to a function library. The linker physically combines the program object 
code (contained in the .OBJ file that is output by the compiler) with the 
object code for any library modules that are called (contained in .LIB files), 
producing a single executable file on the disk (.EXE). At run-time, the 
entire file is loaded into memory, producing a executable image that con¬ 
tains both program and function library code. 

In contrast, Figure 2.3 illustrates the linking procedure for an OS/2 pro¬ 
tected mode application that calls routines belonging to a dynamic-link 
library. The primary distinguishing feature of the dynamic linking mecha¬ 
nism is that the code in the library file is not bound to the program by the 
linker, but rather is stored in a separate file (the dynamic-link library, which 
has a .DLL extension) that is read into memory when the program is run. In 
other words, the binding of code is delayed from link-time to load-time. 

In the same manner as the standard linking procedure, the linker proc¬ 
esses both an object file (.OBJ) and a library file (.LIB). Although the 
library file used for dynamic linking is given the usual .LIB extension, it is a 
special library file known as an import library . An import library does not 
contain the actual function code; rather, for each dynamic-link function, 
it contains a definition record that gives the name of the dynamic-link 
library file on disk that contains the function, and the entry point of the 
function within this library. This information is stored in the .EXE file 
header in relocation records that are used when the program is run. Thus, 
external function references are resolved not by binding in actual code, but 
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FIGURE 2.2: The standard linking mechanism 

by writing records for each function that tell the loader how to resolve the 
references when the program is run. 

Each of these relocation records in the .EXE header contains the follow¬ 
ing information: 

♦ The name of the dynamic-link library 

$ The name of the specific function within the dynamic-link library 
(this name identifies the entry point for the function; an entry 
point can optionally be identified by an ordinal numeric value) 

* A pointer to a list of references to this function within the code 
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FIGURE 2.3: The dynamic linking mechanism 


When the program is run, the loader first reads the program code into mem¬ 
ory; it then loads all requested dynamic-link library files that have not 
already been loaded. Finally, it “fixes up” all references within the program 
code to dynamic-link functions by supplying the actual far address (that is, 
selector and offset) of the function in memory. Thus, all calls to dynamic- 
link functions become intersegment direct calls to the entry points of the 
functions in memory. 

Since the OS/2 operating-system services are supplied as dynamic-link 
libraries, accessing these services from high-level languages is very efficient; 
rather than requiring an indirect interface function such as intdos, invoca¬ 
tions to operating-system services become direct calls to the OS/2 code in 
memory. The name of the import library for the OS/2 function calls is 
DOSCALLS.LIB. Therefore, if your program contains any of these calls 
(such as the call to DosQCurDisk in the example in the previous section), 
you must specify the import library DOSCALLS.LIB as one of the library 
files when linking the program (this file is automatically specified when 
compiling and linking the program using the protected mode version of the 
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Microsoft C compiler through the CL command). The actual code for the 
OS/2 services is contained in a variety of dynamic-link libraries, such as 
DOSCALLl.DLL and VIOCALLS.DLL. These library files must there¬ 
fore be in the path specified by the LIBPATH configuration command. The 
details of calling dynamic-link functions and linking your program with 
them are discussed in Chapters 4 and 5. 

The dynamic linking mechanism, however, is not the exclusive province 
of the operating system. Any software developer can package a set of func¬ 
tions as a dynamic-link library; application programs can access these 
functions in the identical manner that they access the services of the operat¬ 
ing system itself. Thus, OS/2 is effectively an open system that can be easily 
extended by adding dynamic-link modules, without modifying the kernel 
code or using undocumented interfaces. In fact, several major enhance¬ 
ments to OS/2, such as the Presentation Manager and the modules of the 
IBM extended edition, are implemented as dynamic-link libraries. Func¬ 
tions in dynamic-link libraries can even call other dynamic-link libraries. 

Dynamic-link libraries can be generated by the linker through use of an 
appropriate definition file, and the corresponding import libraries pro¬ 
duced by the Microsoft IMPLIB utility. The topic of developing these 
libraries is discussed in Chapter 10. 

An important feature of dynamic-link libraries not indicated in Figure 
2.3 is that several concurrent applications can share a single dynamic-link 
library module that has been loaded into memory. A dynamic-link library is 
loaded when it is first referenced by an application program (a client ). 
When subsequent applications reference this same library, the loader does 
not read in a new copy but rather allows the applications to share the library 
code segments that have already been loaded. When the last client termi¬ 
nates (that is, when the reference count goes to zero), the dynamic-link 
library is freed from memory. Although dynamic-link library code seg¬ 
ments are automatically shared, there are two types of data segments. First, 
there may be a single global data segment, which is initialized only when the 
library code is first loaded and is shared among all clients. Second, there can 
be separate instance data segments for each client that are not shared. Both 
types of data segments are accessed by the dynamic-link library on behalf of 
its client processes. The dynamic-link library code is unaware of the number 
of applications that are sharing its code, and it must synchronize the activ¬ 
ities of an unknown number of client processes. See Chapter 10 for details 
on developing a dynamic-link library. 

In addition to the advantage of being able to share dynamic-link library 
code among multiple applications and thereby reduce memory require¬ 
ments, dynamic linking offers several other advantages over the standard 
linking mechanism. First, with the standard linking method, a separate 
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copy of the library code must be stored in each .EXE file on disk. With 
dynamic linking, however, each .EXE file stores only the names and entry 
points of the functions; only a single copy of the code is stored on disk (in a 
.DLL file), and therefore disk space is saved. Second, if the code in a stan¬ 
dard library file is modified, all calling applications must be recompiled 
(and possibly redistributed to the users); changes can be made to dynamic- 
link libraries, however, that will globally affect the behavior of all calling 
programs without the need to recompile these programs. Finally, although 
loading the first application that references a dynamic-link library is slower 
than loading a normally linked program (since separate files must be read 
rather than a single executable image), loading all subsequent applications 
that use the same library is faster, since the .EXE file is smaller and the 
library code is already in memory. 

The ability of a dynamic-link library to share its code among several 
processes is a good example of an OS/2 feature that relies heavily on the 
hardware support provided by the 80286 processor in the protected mode. 
If several independent processes were to share a single code segment under 
the 8088 processor or under the real mode of the 80286, there would be no 
way to prevent a miscreant process from corrupting this area of memory, 
possibly sabotaging all other processes executing the same code. Under the 
protected mode of the 80286 processor, however, a program cannot write to 
a code segment. Not only would a write attempt fail, but it would also trig¬ 
ger an exception , which is a processor event that returns control to an error¬ 
handling routine in the operating system. OS/2 can then take corrective 
action, such as terminating the offending process and printing an error mes¬ 
sage, while all other processes continue unharmed. This protection mecha¬ 
nism thus maintains the integrity of the overall system. 

Note that the 80286 processor also allows dynamic-link libraries to main¬ 
tain private data segments for each process; a given process cannot access a 
nonshareable segment belonging to another process. This feature is also 
based on the hardware protection provided by the 80286, and will be 
explained in the section on virtual memory later in the chapter. 

Under the dynamic linking mechanism that has been described so far, all 
dynamic-link libraries containing functions called by the program are auto¬ 
matically loaded into memory at the same time the program itself is loaded. 
This procedure is known as load-time dynamic linking . There is, however, 
an alternative mechanism known as run-time dynamic linking . By means of 
run-time dynamic linking, you can load dynamic-link libraries at any time 
during the execution of the program by means of an explicit call to the func¬ 
tion DosLoadModule, passing the name of the file. You must then deter¬ 
mine the address of the specific function you want to call through the 
DosGetProcAddr service; this address is stored in a memory pointer and is 
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used to indirectly call the function. When the program is finished with the 
module, it must explicitly free it from memory by calling DosFreeModule). 
Run-time dynamic linking is thus considerably less convenient than load¬ 
time dynamic linking (in which the program simply calls the desired func¬ 
tion and all details are handled automatically by the linker and loader); 
also, the programmer must know the exact name of the library containing 
the function as well as the name or ordinal value of the function within the 
library (for the load-time method, this information is supplied automati¬ 
cally by the import library). However, for applications that access large, 
infrequently used library modules, run-time dynamic linking allows the 
program to conserve memory by loading these modules only when and if 
they are needed. The sequence of steps for using the run-time dynamic link¬ 
ing functions is discussed in Chapter 8. 

Note that the OS/2 protected mode also supports the traditional method 
of function linking. In fact, the standard Microsoft C function library for 
OS/2 is implemented as a collection of object modules bound into the code 
at link-time using the standard linking mechanism. (Note that Microsoft C 
version 5.1 provides an alternative version of the C library that can be con¬ 
verted into a dynamic-link module, so that standard C library functions can 
be linked dynamically rather than statically.) 

Table 2.1 summarizes this section by listing the most important differ¬ 
ences between standard libraries and dynamic-link libraries. 



Standard Libraries 

Dynamic-Link Libraries 




Method Generated 

By LINK 

By Link with a special 
definition file (.DEF) 

Bound to Application 

At link-time 

At load-time or run-time 

Code Stored on Disk 

In each .EXE file 

In a single, separate .DLL 
file 

Code in RAM 

In the executable 
image with program 
code 

In a separate segment 

Type of Call Used 

Near or far 

Always far 


TABLE 2.1: Differences between Standard Libraries and Dynamic-Link Libraries 
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Standard Libraries 

V 

Dynamic-Link Libraries 

W 

Sharing 

None—a separate 
copy for each 
program 

Multiple applications can 
share code and data 

Operating-System Mode 

MS-DOS, OS/2 real 
or protected mode 

OS/2 protected mode 
only 

Used by 

Application modules 

Operating-system and 
application modules 

, „ T • 1 _ T :i __^ r- 


TABLE 2.1: Differences between Standard Libraries and Dynamic-Link Libraries 


(continued) 

Multitasking and Interprocess Communication 

Chapter 1 defined the three levels of multitasking supported by OS/2: 

1. Multiple concurrent screen groups 

2. Multiple concurrent processes within a screen group 

3. Multiple concurrent threads within a process 

The user of the computer is primarily involved with the highest of these 
levels: multiple screen groups. The user typically starts simultaneous pro¬ 
grams running in different screen groups, and then manually switches 
between them using the system hotkeys. The user may not even be aware of 
the existence of multiple processes or threads within a single screen group. 

The programmer , however, is principally involved with the second two 
levels- multiple processes and multiple threads. The OS/2 application pro¬ 
gram interface provides a wealth of services that allow you to create and 
manage concurrent processes and threads. A detailed discussion of writing 
multitasking applications is postponed until Part Three of this book, after 
the methods for writing single-thread protected mode applications have 
been fully explored. Note, however, that even if your program makes no 
explicit use of multitasking (for example, an MS-DOS application that has 
been converted to run in the protected mode), the user can still benefit from 
the multitasking features of OS/2 by concurrently running several of these 
single-thread applications in separate screen groups. 
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The multitasking features of OS/2 provide a powerful set of tools for 
solving complex programming problems, and for writing efficient and 
responsive programs. Specifically, using multiple processes or threads can 
simplify the design and enhance the efficiency of programs that can be 
divided into a collection of distinct concurrent tasks. An example is a com¬ 
munications program that must simultaneously read characters from the 
serial port, display characters on the screen, read characters from the key¬ 
board, and send characters to the serial port. A single-thread application 
would have to intertwine these logically distinct tasks into a single sequence 
of instructions, which could become quite complex and inefficient. The 
multitasking features of OS/2, however, would allow you to divide such a 
program into a set of simple, concurrent functions. 

Although a complex application can often be divided into a set of rela¬ 
tively simple and distinct tasks, these tasks are seldom autonomous. Indi¬ 
vidual tasks, whether they are processes or threads, must frequently 
synchronize their activities with other tasks. For example, a task that is 
reading characters from a buffer might have to wait for another task that 
is placing characters into this buffer. As another example, you may need to 
make certain that only a single task at a time accesses some common 
resource, such as a shared segment of memory. To allow synchronization 
between tasks, OS/2 provides a wealth of services for interprocess com¬ 
munication. This topic is treated in Chapter 7. 

Virtual Memory 

At the level of an application program, the methods used for specifying 
memory addresses in a protected mode program are similar to those used in 
a real mode program. Under both modes, a complete address consists of a 
two-byte segment value and a two-byte offset value. However, the underly¬ 
ing hardware addressing mechanism employed by the 80286 processor in 
the protected mode is drastically different from that used in the real mode. 
The memory space maintained by the protected mode is known as virtual 
memory. This section begins by briefly describing the hardware mechanism 
that supports virtual memory, and then discusses the implications of virtual 
memory for the programmer and introduces some of the new operating- 
system features that this addressing scheme makes possible. 

The Hardware Mechanism 

The entire virtual memory mechanism, with its many far-reaching implica¬ 
tions for application programs, is based upon the following simple concept. 
Under the real mode, the segment portion of an address contains the actual 
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physical address of the base of the segment in memory. Under the protected 
mode, however, the segment portion of an address contains an index into a 
table in memory that stores the physical segment addresses, as well as other 
important information on each segment. In both modes, the offset contains 
the displacement in bytes of the target memory location from the segment 
base (the maximum offset is 64 kilobytes). It is this added level of address¬ 
ing indirection that makes possible all of the features of virtual memory. 

Figure 2.4 illustrates the real mode addressing mechanism, and Figure 
2 5 shows the mechanism used in the protected mode. In protected mode, 
the segment portion of an address is known as a selector, and the table of 
segment addresses and information is termed a descriptor table. The selec¬ 
tor points to a specific entry in the descriptor table, known as a segment 
descriptor. When your program first addresses a new segment, the pro¬ 
cessor must use the selector to obtain the actual physical address of the base 
of the segment from the appropriate segment descriptor. Note, however, 
that the offset is used in exactly the same manner as under the real mode 

You need to know two more important facts regarding the protected mode 
addressing mechanism to understand the features of virtual memory. First, 
thprp are actuallv two types of descriptor tables used in the protected mode: 


♦ A single global descriptor table, which is accessible to all processes 
in the system 

❖ A separate local descriptor table for each process, which can be 
accessed by that process only 
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FIGURE 2.5: The protected mode addressing scheme 


Second, in addition to the physical address of the base of a segment, a seg¬ 
ment descriptor stores other information regarding this segment. Among 
the important items of information are the following: 

♦ Whether the segment is present in memory, or has been temporar¬ 
ily swapped out to disk (the presence bit) 

♦ The privilege level of the segment (discussed in the next section) 

♦ Whether the segment is executable (that is, whether it is a code 
segment or a data segment) 

♦ The size of the segment (the segment limit , a value up to 64 kilo¬ 
bytes, which is the maximum segment size) 

Large Memory Space and Segment Movement 
One of the major benefits of the virtual memory mechanism of the pro¬ 
tected mode is that it allows programs to address a logical memory space 
that is much larger than the actual amount of physical memory installed in 
the machine. Segments that do not fit in memory are temporarily stored on 
a disk, and the descriptors for these segments indicate that the segment is 
not present in memory. If a program addresses a segment that is not present, 
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the processor generates an exception that passes control to an operating- 
system routine that reads the segment back into memory. (If the existing 
segment at the target address has been altered, the operating system must 
first save it on the disk; if the existing segment has not been altered, it is sim¬ 
ply discarded.) 

Each process may address a virtual memory address space having a theo¬ 
retical limit of 1 gigabyte (approximately a billion bytes); this space consists 
of a half-gigabyte of global segments (accessed through the global descrip¬ 
tor table) and a half-gigabyte of local segments (accessed through the local 
descriptor table belonging to the process). Note, however, that due to the 
limitations of current storage devices and the OS/2 32-megabyte boundary 
on a logical disk volume, the 1-gigabyte theoretical limit is far from 
attainable. 

The program directly accesses this address space as if it were entirely 
present in memory; all the details of swapping segments between primary 
and secondary storage are handled invisibly by the hardware and the 
operating system. The allocation of virtual memory that exceeds the 
amount of physical memory installed in the system is termed memory 
overcommitment. 

The protected mode addressing mechanism not only allows overcommit¬ 
ment of memory, but also permits the operating system to move segments in 
physical memory. If the operating system were to move a segment to a dif¬ 
ferent address in memory under the real mode, all occurrences of the seg¬ 
ment address stored within programs would become invalid. However, 
since protected mode programs store selectors rather than physical 
addresses, the operating system may move a segment in physical memory 
simply by adjusting the address kept in the segment descriptor; all occur¬ 
rences of the selector for this segment would remain valid and would auto¬ 
matically point to the new segment location. Thus, the operating system 
may rearrange segments in physical memory to make the most efficient use 
of memory space as segments are allocated and released. (Since the operat¬ 
ing system allocates variable-size segments, blocks of free memory tend to 
become scattered in memory and it becomes more difficult to satisfy alloca¬ 
tion requests; segment movement allows the operating system to consoli¬ 
date these free blocks.) Note that OS/2 does not move certain areas of 
memory, such as the area used by real mode programs, the ROM BIOS, 
I/O buffers, and the operating-system code itself. Figures 1.8 and 1.9 illus¬ 
trate the fixed and movable areas of memory. 

As mentioned in Chapter 1, the MEMMAN configuration command 
allows you to disable both swapping (the temporary storage of segments on 
disk to make room for other segments) and moving (the rearrangement of 
segments in physical memory to optimize memory use). Both of these proc¬ 
esses are important for maintaining the large, efficient address space required 
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by a typical multiuser system. However, these mechanisms demand time and 
can cause slight delays in system response; therefore, for time-critical appli¬ 
cations such as real-time equipment control systems, you might need to dis¬ 
able one or both of these processes to minimize the program’s response 
time. (Note, however, that if swapping is enabled, you cannot disable 
moving.) 

Protection 

Another important benefit of the virtual memory scheme is that this mech¬ 
anism allows the processor to protect the segments of memory used by one 
process from being corrupted by the actions of another process. Three 
examples of how segments are protected under virtual memory follow. 

First, the code and data segments belonging to one process cannot nor¬ 
mally be accessed by another process. This isolation of private segments is a 
direct result of the fact that a given process has its own local descriptor table 
containing the addresses of its private segments. Another process would have 
a different local descriptor table, containing a different set of addresses. 
(Remember that there is a global descriptor table for segments that are to be 
shared by all processes; also, a given segment can be shared between two or 
more processes by placing descriptors that point to the same segment in 
memory into each local descriptor table.) 

Second, a program cannot normally execute a data segment or modify a 
code segment. Remember that the segment descriptor indicates whether a given 
segment contains code or data. This form of protection prevents a program 
from corrupting its own code, and also makes it safe for several processes to 
share a single code segment (belonging, for example, to a dynamic-link 
library). Note that the operating system can also indicate in the descriptor 
table that a code segment may not be read, or that a data segment may not 
be altered; that is, a read-only data segment. (Under OS/2, there is an 
exception to these limitations. If an application owns a data descriptor for a 
given segment in memory, the operating-system command DosCreateCS- 
Alias will return a code descriptor to the same segment. This second 
descriptor is known as an alias, and allows a program to perform such 
actions as generating or modifying its own code.) 

Third, the processor always checks the offset portion of an address 
against the limit field of the segment descriptor, and does not allow a pro¬ 
cess to reference a memory address beyond the end of the segment. Thus, a 
program is prevented from inadvertently corrupting data belonging to 
another segment. 

Note that an application program cannot access either global or local 
descriptor tables, and is thus prevented from circumventing the memory 
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protection provided by descriptor tables. When the processor detects a vio¬ 
lation of any of these forms of memory protection, it generates an excep¬ 
tion that passes control to an error-handling routine in the operating 
system, which can abort the miscreant process or take other appropriate 
action. Memory protection is an important feature of a multitasking sys¬ 
tem, which must maintain the integrity of the system despite any action of 
an individual process. 


Other Restrictions 

In addition to the limitations placed on the programmer by the protection 
mechanisms discussed above, the protected mode addressing scheme con¬ 
strains the programmer in other ways. Several of these additional restric¬ 
tions are as follows: 

« You cannot store arbitrary values in segment registers (CS, DS, 

ES, and SS). As soon as a value is loaded into a segment register, 
the processor checks whether the value is a valid segment selector, 
and if it is not it generates an exception. Therefore, you cannot use 
these registers for temporary storage or other nonstandard pur¬ 
poses, and you should obtain segment values from the linker, the 
loader, the operating system, or occasionally from another 
process. 

♦ You cannot perform segment arithmetic. Under the real mode, a 
program may arithmetically increment the contents of a segment 
register to access contiguous areas of memory. Under the protected 
mode, however, a segment register contains an index, and per¬ 
forming arithmetic on its contents will cause unpredictable results. 
There is, however, an exception to this rule: OS/2 provides services 
for allocating and releasing blocks of memory consisting of more 
than one 64-kilobyte segment. These blocks are described as huge 
memory allocations. OS/2 returns the selector to the first segment 
belonging to the block, and provides a special increment value that 
may be added to the selector (repeatedly, if necessary) to obtain the 
selectors for subsequent segments in the block. Thus, you can 
write an algorithm to traverse the multiple-segment allocation. See 
the section on huge memory management functions in Chapter 8. 

❖ You cannot access a segment that has a higher privilege level than 
that of the current process. See the section on privilege levels later 
in the chapter. 
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OS/2 Memory Management Services 

The OS/2 memory management features discussed so far—the mainte¬ 
nance of a large virtual address space and the various forms of protection— 
operate automatically; your program must obey certain basic rules, but you 
do not have to write special code or make function calls to take advantage 
of these features. OS/2 also provides a variety of services that your pro¬ 
gram can explicitly call to obtain and manage segments of memory in addi¬ 
tion to those allocated for program code and data when the program is 
loaded. Some of the memory management tasks you can perform by calling 
the OS/2 API are as follows: 

♦ Allocate and free multiple segments 

♦ Change the size of an allocated segment 

♦ Allocate and free blocks of memory consisting of several segments 
{huge segments) 

♦ Allocate and free small blocks of memory within a segment that 
has already been allocated 

♦ Obtain the size of the largest block of free memory 

♦ Share segments among several processes 

♦ Execute a data segment 

See Chapter 8 for a list of the actual function calls and a description of 
how these functions are used. 

Privilege Levels 

Another important protection mechanism, which is built into the 80286 
processor and supported by OS/2, is the maintenance of distinct privilege 
levels . As mentioned in the preceding section, the 80286 processor—in the 
protected mode—maintains a descriptor for each segment in memory. One 
of the items of information stored in this descriptor is a privilege level, 
which is a value from 0 to 3. The highest privilege level is 0, and the lowest is 
3. Thus, every segment, whether it is a code segment or a data segment, has 
an associated privilege level. 

Not only is there a privilege level for each code and data segment in mem¬ 
ory, but there is also a privilege level associated with each task that is cur¬ 
rently running (known as the current privilege level). A task executes a 
sequence of instructions belonging to some code segment; the privilege level 
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of a task is the privilege level of the code segment that it is currently execut¬ 
ing. (Note that task is a general term referring to a single stream of execu¬ 
tion in a multitasking system. An individual task under OS/2 is termed a 
thread.) 

Figure 2.6 illustrates the four privilege levels and the types of tasks that 
typically run at each of these levels under OS/2. The operating-system ker¬ 
nel runs at the highest privilege level (0), and normal applications run at the 
lowest level (3). To protect the integrity of the system, a task that runs at a 
specific privilege level is restricted in two ways: it cannot access segments at 
a higher privilege level, and there may be certain machine instructions that 
it is not free to use. 

Restricted Segment Access 

The basic rule for segment access is that a task executing at a given privilege 
level cannot access—read, write, or execute—a segment at a higher priv¬ 
ilege level. In the illustration of Figure 2.6, each concentric ring represents a 
privilege level; a task can access segments within its own ring or segments 
outside of this ring. The operating-system kernel can therefore access all 
segments in the system, and normal applications can access only segments 
that also have a privilege level of 3. Note, however, that for a task to access a 
segment, the descriptor for this segment must be contained in either the 
global descriptor table, or in the local descriptor table belonging to the task. 



FIGURE 2.6: Privilege levels under the 80286 
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(Maintaining separate local descriptor tables, and having distinct privilege 
levels, are thus two independent mechanisms for protecting memory.) 

The following are some specific programming implications of the access 
restrictions among segments of dissimilar privilege level: 

♦ A program cannot read or write data that is contained in a seg¬ 
ment that has a higher privilege level. Therefore, for example, the 
operating-system kernel can manipulate data belonging to applica¬ 
tions, but applications cannot examine or modify the data main¬ 
tained by the operating system at level 0 (such as the area of 
memory containing segment descriptors and other sensitive data). 

♦ A program cannot directly call or jump to code that is contained in 
a segment at a higher privilege level. Thus, a program cannot sim¬ 
ply call or jump to code within the operating system in order to 
instantly gain a higher privilege level. 

♦ Under the 80286, a program also cannot call a procedure con¬ 
tained in a lower privilege segment. A possible rationale for this 
limitation is that it is not necessary for more privileged code to call 
less privileged code, since it already has potential access to all the 
resources available to the less privileged code. 

Given the rules for segment access that have been outlined so far, how 
can a program call more privileged code within the operating system to gain 
access to the services provided for application programs? To allow limited 
access to more privileged code, the 80286 uses a special type of descriptor 
known as a call gate . A call gate has its own privilege level, but contains a 
pointer to a code segment at a higher privilege level. When the privilege level 
of a call gate matches the current privilege level, a program can invoke an 
intersegment call to the call gate rather than to a normal segment descriptor. 
The call gate mechanism then reroutes control to the higher-privileged code. 
Using this indirect device, programs can access selected entry points within 
the operating-system kernel, and temporarily run at a higher privilege level 
within the operating-system code. Note that a call gate can be created only 
by the highest-privileged code, since it is located within a descriptor table. 

The privilege rule for a stack segment is more stringent than that for nor¬ 
mal data segments. For a process to use a given stack segment (that is, for it 
to load the stack segment selector into the SS register), the privilege level of 
the stack must exactly match the current privilege level of the process. 
Therefore, when a program invokes a higher-privileged code segment 
through a call gate, the processor must switch to the stack belonging to the 
higher-privileged segment, and will automatically copy any parameters 
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onto the new stack (automatic copying of parameters is optional, however). 

In the 80286 protected mode, software interrupt instructions (INT) are 
also routed through gates (there are several special types of gates for inter¬ 
rupt instructions). These gates obey the same access rule as call gates: the 
privilege level of the caller must match the level of the gate. Although 
the 80286 does not explicitly prohibit a low-privilege-level program from 
using the interrupt instruction, interrupt gates under OS/2 are assigned a 
privilege level that prevents application programs from accessing interrupt 
routines. Therefore, OS/2 protected mode programs may not issue the 
interrupt instruction. (The INT machine instruction is normally accessed 
from a C program through library functions such as int86; these functions 
have appropriately been eliminated from the protected mode version of the 
library.) 

Under MS-DOS, software interrupt instructions are typically used for 
accessing the services provided by both the operating system (primarily 
interrupt 21h) and the BIOS (basic input/output system stored in read-only 
memory). These interfaces, however, are no longer needed under OS/2. As 
mentioned in the section on dynamic-link libraries, OS/2 services are now 
accessed by calling dynamic-link libraries. Also, many of the services tradi¬ 
tionally provided by the BIOS are now offered by the operating system. A 
good example is the rich array of OS/2 video services ( Vio ...), which offer a 
level of control over the screen formerly available only through the BIOS. 
Furthermore, a protected mode program is generally not free to call the 
BIOS, since the standard BIOS code cannot run in the protected mode. 

Note also that OS/2 protected mode application programs do not have 
access to the table of interrupt vectors (known as the interrupt descriptor 
table.) Therefore, these programs cannot directly intercept hardware or 
software interrupts (a practice that is common under MS-DOS). Only 
device drivers are permitted to contain hardware interrupt handlers; the 
operating system itself receives initial control when a hardware interrupt 
occurs, and then passes control to the appropriate device driver routine. A 
normal application may also register a function that is to receive control 
when one of several processor exceptions occurs (these interrupts fall within 
the range of OOh to lOh; see the function DosSetVec). 

Restricted Instructions 

Another type of protection based upon privilege levels is the restriction of 
certain machine instructions to selected privilege levels. In general, these are 
instructions that can circumvent the control maintained by the operating 
system and can affect the entire system. There are two categories of such 
instructions. First, there are several machine language operations that may 
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be executed only by a task running at privilege level 0, and they are therefore 
available exclusively to the operating system. These instructions are useful 
primarily for managing multiple tasks in the protected mode, and are as 
follows: 

CLTS Clear TS (Task-Switched) bit in Machine Status Word 

HLT Halt 

LGDT Load global descriptor table register 

LIDT Load interrupt descriptor table register 

LLDT Load local descriptor table register 

LMSW Load machine status word register 

LTR Load task register 

* Any instruction that alters the IOPL bits in the flag word 
(FLAGS) register 

Second, the following machine instructions can be used only by a task 
running at the current IOPL privilege level or at a higher level: 

CLI Disable interrupts 

IN/INS Read port 

LOCK Lock bus (instruction prefix) 

OUT/OUTS Write to port 

STI Enable interrupts 

* Any instruction that alters the Interrupt Enable bit in the 
flag word (FLAGS) register 

The operating system can adjust the current IOPL privilege level by setting 
two designated bits within the flag word register, and thus this set of instruc¬ 
tions can be made available to various privilege levels. For example, if the 
IOPL bits were set to 3, any privilege level could use these operations. 

OS/2 sets the current IOPL to privilege level 2. Therefore, to allow a 
task to use the instructions listed above, OS/2 must run the task at privilege 
level 2 instead of the usual level 3. To force the operating system to run a 
task at level 2 and permit access to the privileged instructions, the following 
rather stringent conditions must be met: 

♦ The code segment containing these instructions must be assigned 
input/output privilege (IOPL) in the linker definition file (.DEF 
file, discussed in Chapter 4). 
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♦ The IOPL configuration command must be set to Yes (see the 
description of configuration commands in Chapter 1). 

♦ A function that calls privileged instructions must generally be writ¬ 
ten in assembly language, since the C library functions that per¬ 
form these operations (^disable, _enable, inp, inpw, outp, and 
outpw) are not provided by the protected mode version of the 
Microsoft C library. 

♦ In future versions of OS/2, it will be necessary to first call the API 
BosPortAccess function to obtain permission to access specific 
ports. When you have finished accessing these ports, you must call 
BosPortAccess again to release them. This function automatically 
grants permission to use the CLI and STI instructions. To use only 
CLI or STI, you may call the API function DosCLIAccess. Note 
that version 1.0 of OS/2 automatically grants permission to use 
any of these instructions and therefore these functions serve no 
purpose; furthermore, this version does not allow you to call a 
dynamic-link library function from a privileged segment . 

See Chapter 4 for an example of a program that contains an IOPL segment 
and uses privileged instructions. 


80286 instructions 

Although a protected mode program is restricted from using certain privi¬ 
leged machine instructions, it is free to use instructions that are unique to 
the 80286 processor. Unlike a real mode program, a protected mode pro¬ 
gram must run on a 80286 (or higher) processor; therefore, it may safely 
take advantage of the instructions unique to this processor that provide 
greater efficiency and ease of programming. Among these instructions are 
the following: 


BOUNB 

ENTER 

IMUL 

(immediate) 

INS 

LEAVE 

OUTS 

POPA 


Check array bounds 

Create stack frame for a procedure 

Integer multiply using constant value 

Receive string from port 
Terminate stack frame for a procedure 
Send string to port 
Pop all general registers 
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PUSH 

(immediate) 

PUSHA 

Shift/Rotate 

(immediate) 


Push constant value onto stack 
Push all general registers 

Shift and rotate using constant value (RCL, RCR, ROL, 
ROR, SAL, SAR, SHL, and SHR) 


Also unique to the 80286 are the privileged instructions that can be executed 
only from privilege level 0, such as CUTS (these instructions were listed in 
the last section, and are not available to an application program). Note that 
all of these instructions are also provided by the 80386 processor. 

If you are programming in Microsoft C, you can use the /G2 command 
line switch to allow the compiler to generate unique 80286 instructions 
where they would be beneficial. If you are programming in assembly lan¬ 
guage, use the .286 directive to enable the assembly of both 8086 and non- 
privileged 80286 operation codes. (The .286 directive in MASM version 5.0 
or later is equivalent to .286C in previous versions; the .286P directive will 
allow all instructions—including privileged—for the 8086 and 80286.) 

Note that if you are writing a program to run under both protected mode 
and real mode, you must not use instructions particular to the 80286. Writ¬ 
ing these dual-mode programs is the topic of Chapter 5. 


Program Entry Conditions 

This section describes the entry conditions of a program that has been 
loaded under the protected mode of OS/2, and contrasts these conditions 
with those of a program loaded under MS-DOS or the OS/2 real mode 
screen group. Specifically, this section covers the initial allocation of seg¬ 
ments, the values assigned to the machine registers at program startup, and 
the information that is provided to a program regarding the hardware 
and software environment in which it is running. 


Program Entry under MS-DOS 

The entry conditions of an MS-DOS program (or a program in the MS- 
DOS compatibility box of OS/2) are quite different from those of an OS/2 
protected mode program. Under MS-DOS, when an .EXE file is loaded, 
the machine registers are set to the following values: 

REGISTER VALUE 


CS 

IP 


Segment address of the code segment 
Offset of initial instruction 
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DS, ES Segment address of the Program Segment Prefix (PSP) 

SS Stack segment address 

SP Offset of top of stack 

Other Ail other registers are set to 0 

The Program Segment Prefix is a lOOh-byte block that precedes the pro¬ 
gram in memory and contains important process information. Some of the 
fields in the PSP are of interest primarily to the operating system; among 
the fields that are useful to an application program are the following: 

♦ The length of the command line 

♦ The command line 

♦ The segment address of the program environment , which is a 
block of memory containing a list of strings indicating the system 
variable settings, such as COMSPEC = C:\COMMAND.COM 
and PATH = C:\UTIL 

Note that the DS and ES registers are initialized to point to the PSP, thus 
making it simple for a program to extract any required information from 
this area during program initialization. However, an MS-DOS .EXE pro¬ 
gram must immediately reinitialize the DS register to the segment address of 
the data segment. Also under MS-DOS, the operating system and ROM 
BIOS services furnish a variety of additional information, such as the MS- 
DOS version number and a list of the peripheral equipment currently 
installed. 


Program Entry under OS/2 

An OS/2 protected mode application may contain many code and data seg¬ 
ments, each of which can be up to 64 kilobytes in length. When a standard 
OS/2 application is loaded, however, the operating system sets up a mini¬ 
mum of three basic segments. These segments are as follows: 

A code segment 

* A automatic data segment; this segment contains initialized and 
uninitialized data, the stack, and a local heap (for dynamic mem¬ 
ory allocation) 


♦ An environment segment 
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The environment segment is similar to the MS-DOS environment, and is 
illustrated in Figure 2.7. This segment begins with a series of strings indica¬ 
ting the current settings of system variables, including some or all of the 
following: 

♦ COMSPEC = xxx, where xxx is the full path name of the protected 
mode command interpreter 

$ PATH = m and DPATH = xxx, where xxx specifies a search path 

♦ PROMPT where xxx is the prompt specification 

$ All other variables assigned by the SET command or by a parent 
process 

Each of these strings is terminated by a zero (an ASCII null character), and the 
last string is terminated by two zeros. Following the environment strings is the 
full path name of the program itself, which also ends with a zero. Next is 
the name of the program exactly as typed on the command line (zero- 
terminated), followed by the command line parameters (exactly as typed, ter¬ 
minated with two zeros). Note that there is a distinct environment segment for 
each process; if a program modifies the contents of its environment segment, 
these modifications will not affect the global settings maintained by the system. 


MA-^ 

(environ [0]) 

Null-Terminated 
Environment Settings 
(e.g., COMSPEC = C:\CMD.EXE) 

00 

n v _ 

Full Path Name of 
Current Program 

0 

□A 

Program Name as Typed 

0 


Parameters 

00 


FIGURE 2.7: The OS/2 environment segment 
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Under OS/2, the initial register settings provide more extensive informa¬ 
tion than those assigned by MS-DOS. The following are the values of the 
registers when a program begins execution: 


REGISTER 

VALUE 

AX 

Selector of the environment segment (this selector can also be 
obtained through the DosGetEnv function) 

BX 

The offset of the program name within the environment 
segment (see Figure 2.7; this offset can also be obtained 
through the DosGetEnv function) 

cx 

The size of the automatic data segment (contains the offset of 
the first byte beyond this segment; a value of 0 indicates a size 
of 65,536) 

DS 

The selector for the automatic data segment 

cs 

The selector for the code segment 

IP 

The offset of the entry point within the code segment 

ss 

The selector for the automatic data segment 

SP 

The offset of the top of the stack within the automatic data 
segment 

ES,BP 

0 

Other 

All other registers are undefined 


In addition to the initial register settings and the contents of the environ¬ 
ment segment, OS/2 also supplies a wealth of system information to a pro¬ 
gram through API function calls. The function DosGetEnv returns the 
selector for the environment segment (contained initially in register AX), 
and the offset of the program name within this segment (contained initially 
in register BX). Therefore, you do not have to save the initial values of these 
registers at the start of the program, but can obtain them when needed. The 
related function DosScanEnv searches the program environment for a spe¬ 
cific variable (such as COMSPEC) and returns the string assigned to this 
variable. 

The function DosGetlnfoSeg returns selectors for the following two seg¬ 
ments containing system information: a global information segment that 
contains data relevant to all processes in the system, and a local information 
segment containing data pertinent only to the calling process. 

The global information segment contains fields that fall into the follow¬ 
ing general categories: 

♦ The time and date (this information is also obtainable from the 
DosGetDateTime function) 
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♦ The operating-system version (this information is also supplied by 
the function DosGetVersion) 

♦ The system status, such as the current foreground screen group 

$ Scheduler parameters, which indicate the basic settings that are 
assigned through the PRIORITY, MAXWAIT, and TIMESLICE 
configuration commands (see the description of configuration 
commands in Chapter 1) 

♦ The boot drive 

♦ Flags for the system trace facility 

The local information segment contains the following items: 

♦ The current process ID (also obtainable through the function 
DosGetPid) 

♦ The process ID of the parent (also obtainable through the function 
DosGetPid) 

♦ The priority of the current thread (also obtainable through the 
function DosGetPrty) 

♦ The ID of the current thread 

♦ The screen group containing the current process 

♦ The subscreen group 

♦ A flag indicating whether the current process is in the foreground 

♦ A flag indicating whether the current process requires the real 
mode 

The exact layouts of these two information segments are represented by the 
structures GlofoallnfoStriict and LocallnfoStruct in the example program 
of Figure 2.8, to be described shortly. Once a program has obtained these 
selectors, it can read the desired information directly from memory, with¬ 
out the need for repeated function calls. Note that these segments are 
marked as read-only for privilege level 3, so that an application program 
cannot alter the system information. 

The function DosGetMachineMode returns a flag indicating whether the 
processor is running in real or protected mode. This function is useful for 
an application designed to run in either of these two modes (the current 
mode indicates, for example, which OS/2 services are available). See Chap¬ 
ter 5 for a discussion of dual-mode programs. 
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The function DosDevConfig returns information on attached devices, 
and is similar to the BIOS interrupt 1 Ih service under MS-DOS. The follow¬ 
ing information is supplied: 

❖ The number of printers attached 

* The number of serial ports 

♦ The number of floppy disk drives 

♦ Whether a math coprocessor is attached 

♦ The PC model and submodel 

❖ The type of display adapter 

In addition to these general functions, services return information rele¬ 
vant to specific subsystems. Among these functions are the following: 


DosGetCP 

DosGetCtrylnfo 

DosGetPrty 

DosMemAvail 

DosQCurDir 

DosQCurDisk 

DosQFHandState 

DosQFilelnfo 

DosQFileMode 

DosQFSInfo 

DosQVerify 

KbdGetCP 


Obtains the code page for the current process 

Retrieves the country-dependent formatting 
information from the COUNTRY.SYS file 

Returns the priority of a specified thread in the 
current process, or of thread 1 in a specified 
process 

Obtains the size of the largest free block of 
memory 

Obtains the current directory for the requesting 
process on the specified drive 

Returns the current default drive for the requesting 
process 

Returns the state of the specified file (for example, 
the access and sharing modes) 

Returns information about a specified file (such as 
the modification date) 

Obtains the mode of the specified file (such as 
normal or read-only) 

Retrieves information on a specified drive 

Returns a value indicating whether the OS/2 verify 
option is active 

Obtains the ID for the code page currently used to 
translate scan codes to ASCII characters 
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KbdGetStatus 

VioGetAnsi 

VioGetConfig 

VioGetCurPos 

VioGetCurType 

VioGetFont 

VioGetMode 

VioGetState 


Obtains the current state of the keyboard 

Indicates whether ANSI support is turned on 

Indicates the current adapter and display types 

Gets the cursor position 

Gets the cursor type 

Returns data on the current video font 

Returns the current video mode 

Returns the palette register settings, the border 
color, or the blink/background intensity switch 


Note that the information supplied by MS-DOS through the program 
segment prefix and BIOS function calls is furnished by OS/2 through the 
initial register values, the environment segment, and the operating-system 
function calls just described. An OS/2 program does not have a program 
segment prefix. 


Entry Conditions in a C Program 

Although the C language does not give you direct access to the initial regis¬ 
ter contents, the Microsoft C compiler furnishes several predefined vari¬ 
ables and library functions for obtaining information on entry conditions 
for protected mode programs. Also, you may call any of the OS/2 informa¬ 
tion functions just described directly from your C program. The following 
are among the variables and functions provided by the C language itself (in 
protected mode): 

argv [0] This string contains the name of the program 

exactly as is was typed on the command line; this is 
the same string that is pointed to by the initial 
value of register BX, described in the preceding 
section. 

_pgmptr In a protected mode C program, this variable 

points to the full path name of the program in the 
environment segment. (In a real mode program, it 
points to the same string as argv [©]). You must 
explicitly declare this variable in your program as 
follows (it is not declared in any of the C header 
files): 

extern char far *_pgmptr; 

_©sm©de This variable contains the value DOS_MOBE 

(= 0) if the program is running in real mode, and 
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geteiiv (varname) 

environ 

_osmajor and 
osminor 


OS2_MODE (= 1) if the program is running in 
protected mode (the variable and constants are 
defined in STOLIB.H). This is the same 
information as returned by the function 
DosGetMachineMode. 

This function searches the program environment 
segment for the variable name vantame, and 
returns the current value of this variable. 

This variable points to an array containing the 
strings listed in the process environment segment. 

As under MS-DOS, these strings contain the major 
(before the decimal point) and minor (after the 
decimal point) operating-system version numbers. 


Note that the variable _psp, which contains the segment address of the 
program segment prefix in real mode C programs, is not present in pro¬ 
tected mode programs (there is no program segment prefix in the protected 
mode). Figure 2.8 lists a protected mode C program that obtains and dis¬ 
plays a variety of program entry information. The program first uses the 
predefined variables and functions listed above. It then calls the OS/2 func¬ 
tion DosGetlnfoSeg to obtain selectors for the global and local information 
segments. The structures defined at the beginning of the program, Global- 
InfoStruet and LocallnfoStruct, serve as templates to allow access to indi¬ 
vidual fields of these two segments. (Note that structures for accessing these 
segments are also provided in an OS/2 header file.,) Finally, the program 
calls DosDevConfig to obtain the number of floppy disk drives that are 
installed. This program can be compiled and linked using the following 
command line (you must use the protected mode version of the C compiler; 
the switches will be explained in Chapter 4): 

cl /G2 /Zp/Lpfig2_8.c 


/* 

Figure 2.8 



This program demonstrates various methods 

for obtaining process 


entry information from a protected mode C 

program. 

*/ 

Prepare the program using the following command line: 

cl /G2 /Zp /Lp fig2_8.c 

#define INCL_DOSINFOSEG 



RGURE 2.8: A protected mode C program demonstrating various methods for obtaining process entry 
information 
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#define INCL_DOSDEVICES 
#include <os2.h> 

#include <stdlib.h> 
tinclude <stdio.h> 
#include <dos.h> 

extern char far *_pgmptr; 


/* In protected mode, points to full path 
/* name of program. 


struct GlobalInfoStruct /* Template for global system information segment. */ 
/*** time *******************************************************************/ 


unsigned long Secondsl970; /* Seconds since 1-1-1970. */ 

unsigned long Milliseconds; /* A freerunning milliseconds counter. */ 

unsigned char Hours; /* Time of day in hours, minutes, */ 

unsigned char Minutes; /* seconds, and hundredths of seconds. */ 

unsigned char Seconds; 
unsigned char Hundredths; 

unsigned int TimeZone; /* Minutes from GMT; -1 means undefined. */ 

unsigned int Timerlnterval; /* Timer interval in 0.0001 second units.*/ 

/*** date *******************************************************************^ 
unsigned char Day; /* Day of month (1-31). */ 

unsigned char Month; /* Month (1-12). */ 

unsigned int Year; /* Year. */ 

unsigned char DayOfWeek; /* Sunday = 0, Monday = 1, etc. */ 

/*** version ****************************************************************/ 
unsigned char Major; /* Major version number. */ 

unsigned char Minor; /* Minor version number. */ 

unsigned char Revision; /* Letter of revision. */ 

/*** system status **********************************************************/ 
unsigned char FGScreen; /* Foreground screen group. */ 

unsigned char MaxSG; /* Maximum number of screen groups. */ 

unsigned char ShiftCount; /* Shift count for huge segments. */ 

unsigned char ProtOnly; /* Flag indicating protected mode only. */ 

unsigned int PID; /* PID of last process to call KbdCharln.*/ 

/*** scheduler parameters ***************************************************/ 
unsigned char DynaVar; /* Flag indicating dynamic variation. */ 

unsigned char MaxWait; /* Maximum wait in seconds. */ 

unsigned int MinTime; /* Minimum time slice in milliseconds. */ 

unsigned int MaxTime; /* Maximum time slice in milliseconds. */ 

/*** boot drive *************************************************************/ 
unsigned int BootDrive; /* Drive from which system was booted. */ 

/*** trace flags ********************************v***************************/ 
char TraceFlags [32]; /* System trace major code flag bits. */ 


far *GlobalInfo; 

struct LocallnfoStruct /* Template for local system information segment. */ 

/*** general information ****************************************************/ 
unsigned int CurPID; /* Current process ID. */ 

unsigned int ParentPID; /* Process ID of parent. */ 

unsigned int Priority; /* Priority of current thread. */ 


FIGURE 2.8: A protected mode C program demonstrating various methods for obtaining process entry 
information (continued) 
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unsigned int ThreadID; 
unsigned int ScreenGroup; 
unsigned int SubscreenGroup; 
unsigned int FG; 
unsigned char RealRequired; 

> 

far *LocalInfo; 


/* ID of current thread. */ 
/* Current screen group. */ 
/* Current subscreen group. */ 
/* Flag => process is in foreground. */ 
/* Flag => process requires real mode. */ 


void main (int argc,char **argv) 

{ 

int i,j; 

char ProgPath [60]; 

unsigned short GlobalSeg, LocalSeg; 

char far *cfp; 

unsigned char NumFloppy; 

/*** Get information from C predefined variables & getenv function ********** j 
printf ("The program name is: %s\n",argv[0]); 

/*** copy path name to local buffer and print with 'printf'. */ 

i = 0; j = 0; 

while (ProgPath [i++] = _pgmptr [j++]) 

printf ("The program path is %s\n",ProgPath); 
printf ("The current COMSPEC is : %s\n",getenv ("COMSPEC")) ; 

printf ("The operating system version is: %d.%d\n\n",_osmajor,_osminor); 
printf ("Contents of the Environment:\n"); 
for (i=0;environ [i][0] 1= '\0'?++i) 

printf ("%s\n",environ [i]); 

/*** Get information from OS/2 global and local information segments. *******/ 
DosGetlnfoSeg 

(SGlobalSeg, /* Receives selector of global information segment.*/ 

SLocalSeg); /* Receives selector of local information segment. */ 

FP_SEG (Globallnfo) = GlobalSeg; 

FP_0FF (Globallnfo) = 0; 

FP_SEG (Locallnfo) = LocalSeg; 

FP_0FF (Locallnfo) = 0; 

printf ("\nThe time is: %2d:%2d:%2d\n" / GlobalInfo->Hours, 
GlobalInfo->Minutes / GlobalInfo->Seconds); 
printf ("The date is: %2d/%2d/%2d\n",GlobalInfo->Month,GlobalInfo~>Day, 
GlobalInfo->Year); 

printf ("Foreground screen group: %d\n",GlobalInfo->FGScreen); 
printf ("Current screen group is: %d\n" / LocalInfo->ScreenGroup); 
printf ("Boot drive: %c\n",64+GlobalInfo->BootDrive); 




/ 


/*** Get information from OS/2 DosDevConfig service. 

DosDevConfig 

(SNumFloppy , /* Receives number of floppy drives. */ 

2, /* Request code: 2 requests number of floppy drives.*/ 

0); /* Must be 0. */ 

printf ("Number of floppy drives is: %d",NumFloppy); 

} /* end main */ 


FIGURE 2.8: A protected mode C program demonstrating various methods for obtaining process entry 
information (continued) 





84 


Programmer’s 
Guide to OS/2 
CH2 


HOW OS/2 IS 
ORGANIZED: 

THE 

PROGRAMMER'S 

PERSPECTIVE 


The description of the structure of OS/2 given in Chapter 1 is presented from 
the viewpoint of the user of the system and focuses primarily on the relation¬ 
ships among multiple screen groups and the session manager. This section out¬ 
lines the structure of OS/2 from the perspective of the programmer . 

Figure 2,9 illustrates the basic components of OS/2, and shows the hier¬ 
archy of control that begins with an application program, passes through 
the layers of the operating system, and ultimately reaches the underlying 
hardware. At the highest layer of this hierarchy are the multiple concurrent 
application programs, which run at the lowest privilege level (3), When 
an application calls either an OS/2 service or a third-party library function, 
control passes to the shared code belonging to a dynamic-link library. Note 
that dynamic-link library functions can call other dynamic-link library 
functions (thus the returning arrow on top of this box). Dynamic-link 
library routines then pass control to the OS/2 kernel, which contains the 
basic code for running multiple processes and managing I/O, and runs at 
the highest privilege level (0), The kernel, however, does not directly manip¬ 
ulate devices, but rather calls upon device drivers, which contain the low- 
level code for managing the specific hardware devices that are installed. 

Figure 2,9 also illustrates a path of control flowing directly from a pro¬ 
gram to a hardware device. An application program may contain one or 
more code segments that are given special I/O privilege (IOPL Segments ). 
These segments run at privilege level 2 and can directly control devices by 



FIGURE 2.9: The hierarchical components of OS/2 that support application programs 
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reading and writing to port addresses. Note, however, that direct device 
control by applications is the exception rather than the rule under OS/2, 
and it is subject to many restrictions. See the section on restricted instruc¬ 
tions, earlier in this chapter, for more information on IOPL segments. 

The flow of control under OS/2 is much more hierarchical and tightly 
organized than under MS-DOS. An MS-DOS program can directly access 
any element in the system: the operating-system interface, the BIOS, the 
hardware, or an arbitrary address in memory. Under OS/2, however, an 
application can access memory and hardware devices only through the spe¬ 
cific channels supported by the operating system. OS/2 is able to enforce 
these restrictions through the hardware protection mechanisms of the 80286 
processor that were discussed earlier in this chapter. In general, as control 
passes from an application program toward the underlying system hard¬ 
ware, higher privilege levels are required. A process, however, cannot arbi¬ 
trarily traverse to a higher privilege level; rather, it must pass through a call 
gate that is explicitly set up by the operating system, which thus has power 
over the allowable channels of control in the system. The call gate is the 
underlying mechanism for many of the arrows indicating transfer of con¬ 
trol in Figure 2.9. 

An important feature of the structure of OS/2 is its inherent modularity 
and flexibility. The kernel is the inner core of the operating system and can¬ 
not be modified; modularity is provided by the layers immediately above 
and below the kernel. The layer above the kernel consists of dynamic-link 
libraries, which form an interface between the kernel and the application 
programs. As discussed in Chapters 1 and 2, the dynamic linking mecha¬ 
nism makes it possible to alter or extend this interface. 

The layer below the kernel consists of the device drivers, which form an 
interface between the kernel and the underlying hardware. By adding or 
replacing device drivers, you can extend the operating system to provide 
support for new hardware devices without the need to modify the kernel 
code. The device drivers supplied with OS/2 fall into two categories. First, 
there is a set of base device drivers, which are located in files (with the .SYS 
extension) in the root directory of the boot disk, and are loaded automati¬ 
cally at system initialization. These drivers manage the basic hardware 
devices, including disk drives, the screen, the keyboard, the printer, and the 
system clock. Table 2.2 lists a typical set of base drivers that may be 
included with OS/2; note that some releases of the operating system may 
supply additional drivers. Also, if there is more than one version of a partic¬ 
ular driver, the file name may include a number; for example, you may find 
the files KBD01.SYS and KBD02.SYS instead of a single file KBD.SYS. 

The second category of device drivers is those that are installed through 
the configuration DEVICE = command. By installing a device driver 
through the configuration file, you can either replace one of the base drivers 
or attach a new driver to the system to support some added peripheral 
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Devise Driver 

Device Supported 

V 

▼ 

CLOCK.SYS 

CMOS clock 

COUNTRY. SYS 

Supports national time, date, and currency conventions 

DISK.SYS 

Disk drive 

KBD.SYS 

Keyboard input 

PRINT. SYS 

Printer 

SCREEN. SYS 

Screen output 


TABLE 2.2: A Typical Base Set of Device Drivers Used by OS/2 


device. (Note that you can replace a base device driver only if that driver is 
for a character device and only if it relinquishes control; character devices 
are defined in the next section.) OS/2 supplies several device drivers that 
you can optionally install; also, hardware vendors may furnish additional 
drivers that you must install to provide support for their devices. Table 2.3 
lists the installable device drivers supplied with OS/2. 

The basic features of OS/2 device drivers are summarized in the next 
section. 


Device Driver 

Function 

V 

v 

ANSI.SYS 

Provides ANSI escape sequence support for 
console I/O in real mode 

COM. SYS 

Supports serial ports 

EGA. SYS 

Supports mouse operations for an EGA display 

EXTDSKDD. S Y S 

Supports one or more external floppy disk drives 

MOUSEAxx.SYS or 
MOUSEBxx.SYS 

Supports a mouse, where xv is a code for the 
specific model of mouse 

POINTDD.SYS 

Draws the mouse pointer on the screen 

VDISK.SYS 

Supports one or more virtual (RAM) disks 


TABLE 2.3: Installable Device Drivers Supplied with OS/2 
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OS/2 DEVICE 
DRIVERS 


An OS/2 device driver provides a basic, uniform set of I/O and control 
services that can be requested by the operating-system kernel. Since device 
drivers handle the low-level, machine-specific details, the kernel can remain 
device independent and can manage a highly divergent set of physical 
devices through a relatively uniform set of commands. The benefit for the 
applications programmer is that programs using the OS/2 API are not 
dependent upon specific hardware configurations but are compatible with 
virtually any devices for which appropriate drivers are supplied. The 
operating-system kernel calls a device driver in the course of executing an 
open, read, or write operation requested by an application. The kernel also 
calls a device driver in direct response to an I/O control command (through 
the function DosBevIOCtl); I/O control commands allow applications to 
send commands to device drivers and perform low-level, device-specific 
operations not available through the standard OS/2 API. Chapter 4 dis¬ 
cusses using I/O control commands to perform low-level operations. 

There are two types of device drivers under OS/2: character and block. 
A block device driver typically manages a direct-access storage device such 
as a disk drive, and transfers blocks of data to and from random locations 
in the device, usually employing direct memory access (DMA). A character 
device driver typically manages devices that read or write a serial stream of 
bytes, such as printers, keyboards, monitors, mice, and serial ports. These 
drivers generally use an explicit I/O instruction for each character transfer¬ 
red (programmed I/O , or PIO ). 

Writing a device driver for OS/2 is a complex task and is beyond the 
scope of this book. However, since application programs interact with 
device drivers (especially monitors , discussed in Chapter 11), it is important 
to understand the basic structure and operation of OS/2 device drivers. See 
the OS/2 Device Driver Guide , supplied with the Software Developer’s Kit, 
for complete details on developing a device driver. 

The Structure of a Device Driver 

Figure 2.10 illustrates the basic structure of an OS/2 device driver. This dia¬ 
gram essentially provides a close-up view of the lower portion of the overall 
structure of OS/2 depicted in Figure 2.9. Note that all requests to a device 
driver pass through the operating-system kernel. The kernel calls the dev¬ 
ice driver strategy routine , passing it the address of a request packet that con¬ 
tains a code specifying the desired operation as well as other information (such 
as a completion flag). Device drivers must provide a standard set of operations 
including initialization, reading or writing a specified number of bytes, and 
device control (IOCTL). When the strategy routine is performing initializa¬ 
tion, it is free to call a subset of the OS/2 API functions; when performing 
other tasks, however, neither the strategy routine nor the interrupt routine 
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(to be described) may call the API. Instead, OS/2 provides a complete set 
of routines specifically designed to fill the needs of device drivers called 
device helpers (or Dev Hips). Note that portions of a device driver can be 
written in C; however, since the DevHlps exchange values directly through 
registers, sections of the code must be written in assembler. 

The strategy routine can handle certain requests immediately (such as 
flushing a buffer or returning a status code). Requests that involve I/O to a 
device, however, can take an unpredictable amount of time; therefore, the 
strategy routine links the packet for such requests into a device request 
queue (using the DevHlp services), and quickly returns control to the kernel 
so that other tasks may begin running, without waiting for the I/O opera¬ 
tion to complete. (Note that the strategy routine may not be preempted; 
therefore, all other threads remain suspended while it is active.) If the hard¬ 
ware device is not busy, the strategy routine may also initiate the device I/O 
operation before returning. If the strategy routine does not complete the 
requested operation itself, it must leave the completion flag in the request 
packet clear. 



FIGURE 2.10: The structure of an OS/2 device driver 
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Once control returns to the kernel, other threads in the system resume 
execution, except for a thread within the kernel that is blocked and waiting 
for the device operation to complete, and the hardware device carries out its 
current operation. When the device finishes its operation, it issues a hard¬ 
ware interrupt that activates the device interrupt routine of the device 
driver. When the interrupt routine receives control, it performs whatever 
actions are appropriate based upon the first uncompleted request packet in 
the request queue (placed there by the strategy routine and removed by the 
interrupt routine). Once the device has been serviced and the operation is 
completed, the interrupt routine may perform one or more of the following 
actions: 

♦ It may set the completion flag in the request packet, indicating that 
the operation is finished. 

♦ It may place an error code in the request packet if the operation is 
not successful. 

$ It may restart the blocked thread in the kernel that is waiting for 
completion of the operation, by calling the DevDone DevHlp 
service. 

♦ It may restart the device if additional operations are needed to 
complete the current request, or if additional requests are waiting 
in the queue. 

<£ It may perform other required actions. 

Note that there is no direct flow of control between the strategy routine 
and the interrupt routine; rather, they communicate through the device 
request queue. Note also that both the strategy routine and the interrupt 
routine have I/O privilege (specifically, the ability to disable and enable 
hardware interrupts, and to address hardware ports); in this regard, they 
are similar to IOPL segments. In addition, the strategy routine should dis¬ 
able interrupts when testing the status of the device or manipulating the 
request queue to prevent contention with the interrupt routine, which can 
become active at any time, through a hardware interrupt. 

The operating system supports both synchronous and asynchronous I/O 
operations in a manner that does not affect the design of the device driver. A 
synchronous I/O process is one in which the requesting thread is suspended 
until the operation is complete. In this case, the kernel simply waits until the 
request is satisfied, and then returns to the calling thread. With an asyn¬ 
chronous I/O request, the operating system returns control immediately to 
the requesting thread without waiting for the operation to complete. In this 




Programmer’s 
Guide to OS/2 
CH2 


case, the kernel creates a new thread that waits for completion, while the 
original thread returns to the application. When the I/O is finally com¬ 
pleted, the thread that had been waiting in the kernel notifies the applica¬ 
tion by posting a RAM semaphore. 

New Features of OS/2 Device Drivers 

The most striking new aspect of OS/2 device drivers compared to those 
written for MS-DOS is their greater degree of complexity. There are three 
important features of OS/2 device drivers that contribute to this added 
complexity. 

First, OS/2 device drivers must operate in a multitasking environment. 
Under MS-DOS, the operating system simply calls the strategy routine and 
then immediately calls the “interrupt” routine. Since there is generally only 
one active task under MS-DOS, the interrupt routine needs to handle 
only one request at a time, and can simply wait until I/O is complete and 
then return to DOS. Note that under MS-DOS, the interrupt routine is not 
activated by an interrupt, and having separate strategy and interrupt rou¬ 
tines is a mere token. Under OS/2, however, a device driver must be able to 
handle requests from multiple processes (which are placed in a queue and 
can be processed in the most efficient order). Also, the device driver cannot 
wait for the completion of I/O, but must return immediately to the kernel 
to avoid blocking other processes; therefore, there is a true need for a dis¬ 
tinct interrupt routine that is activated only when the device is ready to be 
serviced. Also, the strategy routine can be called by another process before 
it has returned from a previous invocation; therefore, its code must be fully 
reentrant. 

Second, an OS/2 device driver must be bimodal , meaning that it must 
function in both real and protected modes. When either the strategy routine 
or the interrupt routine receives control, the system may be in real mode or 
in protected mode. 

The problem is that an address saved in one mode (for example, the 
address of the user’s buffer) will not normally be valid in the other mode. 
(As explained in the section on virtual memory, the real mode uses physical 
segment addresses and the protected mode uses virtual segment selectors.) 
OS/2 employs two mechanisms to overcome this problem. First, the 
address of the request packet (as well as several addresses contained in 
the request packet) are bimodal addresses . A bimodal address is one that is 
carefully constructed so that the selector value is the same as the physical 
segment address that it indexes. These addresses can therefore be used in 
both real and protected modes. 

Second, the kernel passes the addresses of I/O buffers to the strategy 
routine as 32-bit physical addresses, which represent the actual linear 
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address of the buffer in the 16-megabyte memory space. Before using one 
of these addresses, the device driver must call the PhysToVirt DevHlp, 
which converts a 32-bit physical address into a segment:offset address if the 
system is in real mode, or into a selectonoffset address if the system is in 
protected mode. Thus, the device driver can easily obtain a valid address 
without knowing which processor mode is active. Note that since the device 
driver stores physical addresses, the operating system must not move the 
addressed segments in memory; therefore, the system locks down the seg¬ 
ment containing the user’s buffer (and other segments by request). 

Another implication of the bimodal operation of device drivers is that the 
driver controlling a given device must regulate real mode programs that are 
attempting to access the same device through ROM BIOS services. Therefore, 
an OS/2 device driver normally contains a routine to trap the appropriate 
BIOS software interrupts invoked by real mode programs, and to serialize 
access to the device that is being controlled (using appropriate semaphores). 
This routine must also prevent a real mode program in the foreground from 
being switched to the background if a time-critical operation is in progress 
(using the DevHlp ROMCritSection). 

Third, MS-DOS device drivers can use the hardware support contained 
in the ROM BIOS. OS/2 device drivers, however, must supply their own 
low-level code, since the standard PC AT BIOS cannot run in protected 
mode. Note, however, that a device driver written specifically for the PS/2 
series of machines can call the advanced BIOS, or ABIOS, supplied with 
these systems, which can run in real mode or protected mode. 

Another unique feature of OS/2 character device drivers is the support 
for monitors. Developing and using monitors is the topic of Chapter 11. 















CHAPTER 


Writing an 
MS-DOS 
Program for the 
Compatibility 
Box 


Part One introduced many of the basic concepts that are important 
for the user of OS/2 as well as for the developer of OS/2 applications. 
This chapter begins the treatment of specific development techniques 
with a discussion of the methods for writing programs to run in the 
OS/2 compatibility environment. This environment is also known as 
the real mode screen group, the compatibility box, or the 3.x box. As 
mentioned in the Introduction, developing a program that can run 
only in the compatibility environment represents the lowest level of 
commitment to OS/2. The techniques, limitations, and rules pre¬ 
sented in this chapter are for developers who are writing or updating 
programs targeted primarily for the MS-DOS operating system, but 
would like these programs also to run in the compatibility mode of 
OS/2; the ability to run under OS/2 is thus a secondary purpose for 
these applications. If a program is targeted primarily for OS/2, it 
should be written to run in a protected mode screen group, using the 
techniques presented in Chapter 4. Chapter 5 subsequently explores 
methods for developing programs that are targeted primarily for the 
protected mode of OS/2, but that can also run under the real modes 
of OS/2 and MS-DOS as a secondary purpose (the goal of Chapter 5 
is thus the opposite of the goal of the current chapter). 
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A program that runs only in the compatibility environment cannot take 
advantage of any of the advanced features of OS/2. In fact, such programs 
often run faster and are subject to fewer limitations when executed under 
MS-DOS. The primary advantage of being able to run an MS-DOS applica¬ 
tion in the compatibility box is that an OS/2 user can load this program 
simultaneously with protected mode applications, and can run it in the fore¬ 
ground whenever desired. 

This chapter assumes that you are already familiar with the basics of 
developing programs for MS-DOS. The emphasis here is on the differences 
between MS-DOS and the compatibility mode of OS/2, and on the addi¬ 
tional rules that you must follow to allow an MS-DOS application to run in 
this environment. The first section briefly describes the basic structure of 
the compatibility environment. The next section presents the rules for 
developing compatibility mode applications, and describes the limitations 
imposed on these applications by OS/2. The last section focuses specifically 
on the rules for developing a standard MS-DOS device driver that can run 
under OS/2. See the book Performance Programming Under MS-DOS, or 
one of the other books on MS-DOS development mentioned in the Bibliog¬ 
raphy, for more information on writing MS-DOS programs and device 
drivers. 


THE 

STRUCTURE 
OF THE 

COMPATIBILITY 

ENVIRONMENT 


Chapter 1 described the basic features of the OS/2 compatibility environ¬ 
ment, its relation to the other elements of the system, and how you can 
switch into and out of this screen group. This section briefly describes how 
the compatibility mode is implemented. 

Recall that you can specify whether the compatibility environment is to 
be included in the system, and you can indicate the amount of memory it 
will occupy, through the PROTECTONLY and RMSIZE configuration 
commands. Figure 1.9 illustrates the location of the real mode programs in 
memory. Remember also that while the compatibility environment is in the 
foreground, the protected mode applications in the background continue to 
receive processor time slices; however, when a protected mode screen group 
is in the foreground, the compatibility environment is suspended—all pro¬ 
grams in this environment stop running. 

The primary goal of the compatibility environment is to emulate MS- 
DOS as closely as possible so that applications can run in this screen group 
exactly as they run under MS-DOS. As illustrated in Figure 3.1, MS-DOS 
programs access the underlying computer hardware in one of three general 
ways. First, they can invoke the services of the operating system, typically 
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by placing appropriate parameters in machine registers and issuing soft¬ 
ware interrupt 21h. Second, to gain greater control over the system hard¬ 
ware and a higher level of efficiency, these programs can call the lower-level 
services of the ROM BIOS. Finally, MS-DOS programs can bypass both the 
operating system and the BIOS—and directly control the hardware by 
reading and writing to port addresses or to specific locations in memory. To 
provide full MS-DOS compatibility, the OS/2 real mode must support all 
three of these channels. 



FIGURE 3.1: The three ways MS-DOS applications access the underlying hardware 

Figure 3.2 illustrates the mechanisms used by OS/2 to provide support 
for MS-DOS programs in the compatibility environment. OS/2 must not 
only provide all requested services, but it must also try to prevent real mode 
programs from interfering with protected mode programs that are sharing 
the same devices or memory locations. There is nothing OS/2 can do to 
control direct hardware access by real mode programs; accordingly, pro¬ 
grams that directly access certain I/O addresses, to be described later in this 
chapter, cannot run under OS/2. OS/2, however, controls requests to the 
operating system and to the ROM BIOS by intercepting the software inter¬ 
rupts used to access these services. 

MS-DOS service requests, most of which are issued through interrupt 
21h, are intercepted by an OS/2 router routine. The OS/2 router passes 
control to the appropriate code in the operating-system kernel. To conserve 
memory and yet provide a rapid response, the code for servicing real mode 
applications is divided into two portions. The most frequently requested 
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FIGURE 3.2: OS/2 mechanisms for supporting real mode applications 

routines are located within the section of the kernel in low memory (see Fig¬ 
ure 1.9). The router calls this code directly, since it can be. executed in real 
mode. For less frequently invoked services, the OS/2 router transfers con¬ 
trol to routines within the high section of the kernel (above 1 megabyte), 
which are also used to service protected mode applications. The code for 
these routines, therefore, does not need to be duplicated in low memory. 
The operating system, however, must first switch into protected mode 
before calling the routine, and then switch back to real mode before return¬ 
ing control to the application, causing a longer response time. 

To access a hardware device, the kernel routine then calls the strategy 
routine of the appropriate device driver (as described in Chapter 2). Note 
that a single device driver can be called by kernel code running in either real 
or protected mode, since OS/2 device drivers are designed to operate in 
both modes. 
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BIOS requests from real mode programs are typically intercepted by an 
interrupt routine belonging to the OS/2 device driver controlling the corres¬ 
ponding device (for example, calls to the BIOS printer services through 
interrupt 17h would be intercepted by the printer device driver). While han¬ 
dling such BIOS requests, the OS/2 device driver is said to be in user mode. 
As mentioned in Chapter 2, there are two reasons for the device driver to 
intercept these requests rather than simply letting a real mode application 
directly access the ROM BIOS. First, since protected mode applications run 
concurrently with the real mode screen group, the device driver must prevent a 
real mode program from interfering with a device that is currently being used 
by a protected mode program. Therefore, it may have to use the semaphore 
mechanism (see Chapter 7) to serialize access to the device. Second, the device 
driver must prevent the user from switching into a protected mode screen group 
during a time-sensitive I/O operation, since the real mode process is totally sus¬ 
pended when placed in the background. The device driver can call the DevHlp 
routine ROMCritSection to temporarily lock the real mode screen group in the 
foreground. 

Once the device driver is ready to allow the real mode program to access 
the device, it has two choices. First, it can handle the low-level device opera¬ 
tions itself, eliminating the need for the BIOS code. Second, it can simply 
invoke the original BIOS routine. Note that when intercepting a BIOS soft¬ 
ware interrupt, the device driver always receives control in real mode; there¬ 
fore, unlike the strategy and hardware interrupt routines, it can safely call 
the ROM BIOS (which can run only in real mode). 


GUIDELINES 

FOR 

REAL MODE 
APPLICATIONS 


The OS/2 compatibility environment closely emulates the environment of 
MS-DOS versions 3.x with the SHARE program loaded (which supports 
network file sharing). Most standard MS-DOS applications will run with¬ 
out modification in the compatibility box. This includes many of the appli¬ 
cations that perform “ill-behaved” actions such as writing directly to video 
memory or calling undocumented operating-system functions. This section 
begins with a summary of some of the specific MS-DOS features that are 
supported by the OS/2 compatibility environment. Following this sum¬ 
mary is a description of the features that are not supported, and then a dis¬ 
cussion of some general differences between MS-DOS and the 
compatibility box. 


Supported Features 

Programs in the compatibility environment run in the real mode of the 
80286 processor. Therefore, they can use all the machine instructions avail¬ 
able in the 8086/88 processors, plus several new instructions provided by 



the real mode of the 80286 (see the section on 80286 instructions in Chapter 
2 for a list of these instructions). In addition to the basic real mode instruc¬ 
tion set, compatibility programs can access many of the system resources 
available to MS-DOS applications. The following is a description of some 
of the most important MS-DOS resources that are supported by the OS/2 
compatibility environment. These resources are found at three levels within 
the system: the operating-system level, the ROM BIOS level, and the hard¬ 
ware level. 

The Operating-System Level 

Almost all of the MS-DOS services provided for application programs are 
available in the OS/2 compatibility environment. Most of these services are 
accessed by placing the number of the desired function in register AH and 
invoking software interrupt number 21h. The available MS-DOS services are 
listed in Table 3.1. Note that the file-sharing support normally provided by the 
MS-DOS 3.x SHARE command is automatically present in the OS/2 com¬ 
patibility environment (consequently, there is no SHARE command in the 
OS/2 real mode). 


MS-DOS 

Interrupt 

Service Provided/Limitations 

V 


20h 

Terminate program 

21h 

Dispatch selected DOS function; all documented functions 
are supported 

25h 

Absolute disk read 

26h 

Absolute disk write; supported only for diskettes 

27h 

Terminate and stay resident 


TABLE 3.1: MS-DOS Services Provided by the OS/2 Compatibility Environment 


In addition to this basic set of services, several undocumented DOS func¬ 
tions commonly used by memory-resident utilities are also provided. For 
example, you can use interrupt 21h, function 34h, to obtain a pointer to a 
flag indicating when DOS (in this case OS/2) is active. This function call is 
illustrated by the short real mode program given in Figure 3.3. 
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/* 

Figure 3.3 


This program demonstrates using the undocumented MS-DOS function 
number 34h in a program run in the compatibility environment. This 
real mode program is prepared using the following command lines 

cl /Zp /Lr fig3 3.c 

*/ 

#include <stdio.h> 

#include <dos.h> 

void main () 

{ 

union REGS Reg? 

struct SREGS SReg; 

unsigned char far *InDosPtr; 


/* Pointer to 'indos' flag. */ 

Reg.h.ah = 0x34; 

intdosx (&Reg,&Reg,&SReg); 

FP SEG (InDosPtr) = SReg.es; 
FP'__OFF (InDosPtr) = Reg.x.bx; 

/* Select function 34h. */ 

/* Invoke interrupt 21h. */ 

/* Save segment of flag. */ 

/* Save offset of flag . */ 

printf ("INDOS flag = %d\n", 

} /* end main */ 

*InDosPtr); 


FSGURE 3.3: A real mode program demonstrating DOS function number 34h 


In addition to providing MS-DOS application services, the OS/2 real 
mode also supports the following interrupt vectors in the same manner as 
MS-DOS: 


Interrupt 22h 


Interrupt 23h 


Interrupt 24h 


Interrupt 28h 


This interrupt vector stores the address of the terminate 
program routine. This address is used by the operating 
system, and the interrupt should not be invoked by your 
program. 

OS/2 invokes this interrupt when it detects a Control-C or 
Control-Break key. You can point this vector to your own 
break-key handler. 

OS/2 invokes this interrupt when it encounters a critical 
error. You can point this vector to your own critical-error 
handler. 

OS/2 repeatedly invokes this interrupt when in an idle 
state—for example, while waiting for keyboard input at the 
operating-system prompt. This interrupt is provided for 
the benefit of background memory-resident programs such 
as print spoolers. 
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The BIOS Level 

Table 3.2 lists the ROM BIOS services that are supported by the OS/2 com¬ 
patibility environment. Note that some of these vectors may actually point 
to routines belonging to OS/2 device drivers, so that the device drivers can 
control access to the devices they control. Accordingly, you must invoke 
these services through the appropriate interrupt vectors and not through 
absolute memory addresses. 

In addition to the basic BIOS services, OS/2 supports several other 
BIOS-level features present in MS-DOS machines. First, the following 
interrupts are invoked by the BIOS: 


Interrupt IBh 

The BIOS invokes this interrupt when it detects a 
Control-Break key. You can point this vector to your own 
break-key handler. 

Interrupt ICh 

The BIOS invokes this interrupt with each clock-tick 
hardware interrupt (approximately 18.2 times per second). 
You can point this vector to your own clock-tick routine; 
note, however, that this routine will not be called when the 
real mode screen group is placed in the background. 

Second, as under MS-DOS, the system consults the parameter tables that 
are pointed to by the following interrupt vectors: 

Interrupt lDh 

This vector points to a table of video initialization 
parameters. 

Interrupt lEh 

This vector points to a table of diskette parameters used 
during system initialization. 

Interrupt IFh 

This vector points to a table of graphics characters for the 
upper 127 ASCII codes. 


Finally, the standard BIOS data area is maintained in low memory. This 
area begins at the address 0040h:00Q0h. It contains a large set of parame¬ 
ters, including the following: 

♦ Addresses of serial and parallel ports 

♦ A list of installed devices 

♦ The amount of memory installed 

♦ The keyboard buffer 

♦ Disk and diskette parameters 
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BIOS 

Interrupt 

V 

Service Provided/limitations 

10h 

Video services. 

llh 

List of installed equipment. 

12h 

Size of memory (reports only the size of the compatibility 
environment). 

13h 

Disk/diskette services. For disk, only functions Olh, 02h, OAh, 
and 15h are supported (no writes). For diskettes, all functions 
are supported. 

14h 

Serial port services. If the OS/2 COM.SYS driver is installed, 
you must enable the serial port in real mode by running the 
SETCOM40 command. 

15h 

System services. All these functions are supported except 
numbers 87h through 91h. 

16h 

Keyboard services. 

17h 

Printer services. 

19h 

Bootstrap loader. 

lAh 

System-timer and real-time clock services. These functions are 
supported except for numbers 02h through 07h. 


TABLE 3.2: ROM BIOS Services Supported by the OS/2 Compatibility Environment 


♦ Video parameters 

♦ Time of day information 

The Hardware Level 

A program that is to run in the OS/2 compatibility environment can take 
direct control over the hardware in several ways. 

First, as under MS-DOS, you can write a hardware interrupt handler and 
redirect a hardware interrupt vector to point to your routine rather than to 
the original handler. This procedure is known as hooking an interrupt. 
Under OS/2, however, there are three important exceptions: 

♦ You cannot hook the CMOS real-time clock interrupt (interrupt 
number 70h). 
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♦ You cannot hook an interrupt that is already owned by an OS/2 
device driven (An example of a hardware interrupt vector that is 
typically owned by a device driver is number 76h 5 which is invoked 
by the fixed disk controller.) 

♦ You can hook the keyboard interrupt (number 09h), even if it is 
owned by an OS/2 device driven 

If your real mode program attempts to hook the real-time clock interrupt or 
an interrupt vector that is already owned, OS/2 immediately stops the pro¬ 
gram and displays the error message shown in Figure 3.4. The system gives 
you the choice of either terminating the program or continuing the program 
without changing the interrupt vector. 


Session Title: command.com 
SYS1927: A DOS mode 

program changed an interrupt vector that 
is owned by the system. The program was ended. 


End the program 

Ignore the error and continue 


FIGURE 3.4: Error message displayed if your program attempts to hook an interrupt 
vector owned by the system 

The following are examples of useful hardware interrupt vectors that 
your program can safely hook: 

Interrupt 08h This interrupt is invoked approximately 18.2 times per 
second by the 8253 timer chip. 

Interrupt 09h This interrupt is invoked each time a key on the keyboard is 
either pressed or released. 

Just as under MS-DOS, you can set the appropriate interrupt vector to 
point to your routine; however, you should save the old address and call this 
address from your routine to avoid blocking interrupt handlers installed by 
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other real mode programs. Note that there are two limitations that may 
affect timing-sensitive interrupt handlers in the real mode of OS/2: 

* Remember that while the real mode screen group is in the fore¬ 
ground, background protected mode threads continue to receive 
processor time slices. If a hardware interrupt occurs while a pro¬ 
tected mode thread is running, the system must switch thread con¬ 
texts and switch into real mode in order to pass control to a real 
mode interrupt handler. The delay engendered by this switching 
procedure could cause applications with stringent timing require¬ 
ments to lose interrupts. 

$ Remember also that real mode programs are suspended when the 
user switches this screen group to the background. Therefore, no 
interrupts are received when the real mode screen group is in the 
background. A handler for the clock-tick interrupt (number 08h), 
for example, must not depend upon receiving an uninterrupted 
sequence of interrupts. Also, a real mode communications pro¬ 
gram that is interrupt-driven will not receive characters when a 
protected mode screen group is in the foreground. 

A real mode program can also control the hardware by directly repro¬ 
gramming the following devices: 

♦ The 8253 timer chip. For example, a program that generates sound 
can reprogram this chip to obtain various frequencies. 

❖ The serial and parallel ports. A real mode program can reprogram 
these devices; however, doing so makes the devices associated 
with these ports unavailable to protected mode programs. 

Features Mot Supported 

It is important to remember that programs within the OS/2 compatibility 
environment run in the real mode, and may therefore not use any of the 
unique protected mode features discussed in this book, such as the OS/2 
application program interface and the large virtual memory space. Further¬ 
more, your program must not switch itself into protected mode by calling 
the BIOS or by directly setting the Protection Enable (PE) bit of the 
Machine Status Word. Also, a program running in the compatibility envi¬ 
ronment cannot use extended memory (that is, memory above 1 megabyte, 
normally accessed through several BIOS services that will be described later 
in this section). Extended memory is reserved for the operating system and 
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protected mode programs. Therefore, you cannot run print spoolers, RAM 
disks, disk caches, or other utilities that use extended memory. Note, how¬ 
ever, that a real mode program can access expanded memory that follows 
the Lotus/Intel/Microsoft expanded memory specification. 

The following is a description of resources that exist in a typical MS- 
DOS machine and that are off-limits for a compatibility environment pro¬ 
gram. These resources are found at the levels of the operating system, the 
ROM BIOS, and the hardware. 

The DOS Level 

First, your program must not demand a specific MS-DOS version. Under 
the initial release of OS/2, the DOS “get version” service (function number 
30h) returns a value of 10.0. Therefore, if your program requires the fea¬ 
tures of MS-DOS version 3.x, for example, you should test that the major 
version number is equal to or greater than 3. 

Also, under OS/2 you cannot perform sector-level writes to a fixed disk 
through DOS interrupt 26h. You can, however, use this function for direct 
writes to floppy diskettes. You should perform all writes to fixed disks 
through the DOS file system (for example, using function 40h, “write to a 
file or device”). 

Another DOS service that has been eliminated from OS/2 is the direct 
access to the DOS PRINT queue that is provided by MS-DOS version 3.x 
through interrupt 2Fh, function 01 h. Under MS-DOS, the PRINT com¬ 
mand installs itself as a memory-resident utility so that it can continue to 
print files in the background while the user runs other programs. Interrupt 
2Fh, function Olh, allows a program to access the services of the resident 
PRINT program. Under OS/2, however, the PRINT program no longer 
remains resident in memory, and therefore this interrupt function is not 
provided. Note that OS/2 provides background printing through the 
SPOOL utility, which services real mode as well as protected mode pro¬ 
grams. 

Finally, Microsoft offers several general suggestions for maintaining 
compatibility with present and future versions of MS-DOS and the OS/2 
real mode environment. Note that these are not absolute rules. Among the 
guidelines are the following: 

❖ Use the file-handle functions rather than the older functions that 
employ file control blocks (FCBs). 

♦ Avoid the character-device I/O functions in the range from Olh to 
OCh. Rather, perform I/O to character devices whenever possible 
through the file-handle functions (for example, function number 
40h, “write to a file or device”). 
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♦ Allocate and deallocate memory through the DOS memory man¬ 
agement services (functions 48h, 49h, and 4Ah). Do not use areas 
of memory not allocated through the operating system. 

♦ Use DOS function 4Bh (“load or execute a program”) for loading 
programs and overlays, rather than the obsolete function 26h 
(“create new program segment”). Also, using function 4Bh is 
superior to writing a custom loading routine that may depend 
upon a specific .EXE header format (the .EXE format is subject 
to change). 

♦ Use DOS function 31h to terminate a resident program, rather 
than interrupt 27h. Function 3lh supports larger programs and 
allows you to return an error-level code to the parent process. 

♦ Use functions 25h and 35h to modify interrupt vectors, rather than 
writing directly to the interrupt vector table in memory. 

♦ Use the .EXE executable file format rather than the .COM for¬ 
mat, which does not contain loading information and is being 
phased out. 


The BIOS Level 

A program that runs in the compatibility environment of OS/2 cannot use 
the following BIOS services: 


Interrupt 05h Under MS-DOS, this interrupt generates a print screen as if 
the Shift-PrtSc keys were pressed. Under OS/2, the 
interrupt is ignored. 

Interrupt 13h This interrupt provides access to the BIOS disk services. 

Under OS/2, for a fixed disk, you cannot use any of the 
functions that write to the disk (such as function 03h, 

“write sectors,” or 05h, “format cylinder”). For a 
removable disk, you can use any appropriate function. 

Also, you cannot use the following BIOS functions, which are accessed 
through interrupt 15h and are provided on 80286 and 80386 machines for 
managing extended memory, switching into protected mode, and sharing 
devices in multitasking systems: 


Function 87h 
Function 89h 
Function 90h 
Function 91 h 


Move block to or from extended memory 
Switch processor to protected mode 
Device busy 
Interrupt complete 
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Finally, under OS/2 you are not free to manage the CMOS real-time 
clock, since this device is the exclusive province of the operating system. 
The following functions, which are accessed through interrupt lAh, are 
therefore off-limits: 


Function 02h 
Function Q3h 
Function 04h 
Function Q5h 
Function 06h 
Function 07h 


Read real-time clock 
Set real-time clock 
Read real-time clock date 
Set real-time clock date 
Set real-time clock alarm 
Reset real-time clock alarm 


The Hardware Level 

As mentioned in the section in this chapter on supported features, you can¬ 
not hook the CMOS real-time clock interrupt (number 70h); nor can you 
hook a hardware interrupt that belongs to an OS/2 device driver (other 
than the keyboard interrupt, number G9h). Also, under OS/2 you cannot 
reprogram the following devices: 

❖ The 8259 interrupt controller 

❖ The disk controller (sometimes remapped by copy-protection 
schemes) 

❖ The DMA controller (sometimes remapped by high-speed com¬ 
munications programs) 


General Differences 

In addition to the specific limitations imposed on MS-DOS applications by 
the OS/2 compatibility box, there are several general differences in the 
behavior of a program running in each of these two environments. 

First, the overall performance of a program can vary between MS-DOS 
and the OS/2 compatibility environment. Whether an application runs 
faster or slower in the compatibility environment depends upon the type of 
application and the current configuration of OS/2. Among the factors that 
tend to make a program run faster under OS/2 are the more efficient file¬ 
handling algorithms and the faster screen-display methods used by this 
operating system. For example, the TYPE command runs approximately 10 
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percent faster under OS/2 than under MS-DOS. Among the factors that tend 
to make an MS-DOS program run slower under OS/2 are the following: 

♦ Protected mode tasks running in the background compete with the 
real mode program for processor cycles. Obviously, the more 
background protected mode programs are loaded, the slower the 
real mode program will run. 

♦ As described in the section on the structure of the compatibility 
environment, some operating-system services require mode switch¬ 
ing, which lengthens response time. 

♦ Hardware-interrupt service routines in real mode programs can 
also necessitate mode switching (as well as switching thread con¬ 
texts) if a protected mode thread is active when an interrupt 
occurs. 

Most MS-DOS applications run in the OS/2 compatibility box with 
acceptable performance. The compatibility environment, however, is 
unsuitable for two general categories of programs. The first category con¬ 
sists of programs that cannot tolerate being temporarily suspended. One 
example is a program that relies upon a steady stream of clock interrupts to 
time events; while such a program is suspended, no interrupts would be 
received and its timing information would become invalid. Another 
example is a real-time equipment control system, which would miss external 
events while suspended. 

The second group of programs that cannot run in the OS/2 compatibil¬ 
ity environment consists of those that must respond to hardware interrupts 
at a high rate. Because OS/2 intercepts hardware interrupts—and may need 
to perform a context and processor mode switch before passing control to 
the real mode interrupt handler—an OS/2 program cannot respond to inter¬ 
rupts as rapidly as an MS-DOS program, which receives interrupts directly. The 
OS/2 interrupt response can be especially slow if there are many protected 
mode threads in the background. An example of a program that may fail 
under the real mode of OS/2 is a terminal emulator that operates at a high 
baud rate. 

The OS/2 print spooler may also cause real mode programs to behave 
differently under OS/2 than under MS-DOS. If the spooler is installed (see 
description of the SPOOL command in Chapter 1), printer output will be 
quickly stored in a spool file, and the program will continue running with¬ 
out waiting for the output to print. The output will normally not begin 
printing until either the printer file is closed (for example, fclose (stdprsi)) 
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or the program terminates. Note, however, that you can flush the print 
spooler and send the output immediately to the printer at any time by press¬ 
ing the Control-Alt-PrtSc key combination. 


Under the OS/2 model for device support, there is a single device driver for 
each physical device. A standard OS/2 device driver receives I/O requests 
from both protected mode and real mode programs. These device drivers 
must be written according to the guidelines given in the OS/2 Device Driver 
Guide , and although they will support real mode applications in the com¬ 
patibility environment of OS/2, they will not run under MS-DOS. 

A limited number of MS-DOS device drivers, however, can be installed 
under OS/2. These drivers are designed to run only in real mode, and they 
can support I/O requests only from programs in the compatibility environ¬ 
ment. Since OS/2 allows a limit of one device driver per physical device, a 
device controlled by an MS-DOS driver remains unavailable to protected 
mode applications. The advantage of these device drivers, however, is that 
you can write a single driver for both MS-DOS and OS/2, and you can fol¬ 
low the relatively simple rules for writing a device driver under MS-DOS. 
For information on writing MS-DOS device drivers, see the IBM DOS 
Technical Reference or Performance Programming Under MS-DOS (both 
books are cited in the Bibliography). 

There are three major limitations placed upon MS-DOS device drivers 
that are to run under OS/2. First, the device driver must be for a character 
device. MS-DOS block-device drivers cannot be installed. Second, the 
character-device driver cannot employ a hardware-interrupt handler. 
Rather than being driven by interrupts, it must poll to determine if the 
device is ready. Note that for an MS-DOS device driver, the operating sys¬ 
tem itself calls the “interrupt routine” (which is therefore an interrupt rou¬ 
tine only by name). Third, the supported character device cannot be either a 
mouse or a clock device. Driving either of these devices with an MS-DOS 
device driver would make them available exclusively to real mode pro¬ 
grams; however, exclusive real mode access to these two devices is not per¬ 
mitted. Examples of MS-DOS device drivers that can be installed under 
OS/2 are old VDI (video display interface) and CON (console) drivers. 

When programming an MS-DOS device driver that is to run under 
OS/2, there is one more restriction. The initialization routine of an MS- 
DOS device driver can call DOS interrupt 21 h functions 01 h through OCh to 
perform I/O, and function 30h to obtain the operating-system version. 
Under OS/2, however, the initialization code cannot call any DOS interrupt 
21 h functions. 
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Note that a device driver following the MS-DOS model is installed in the 
same manner as an OS/2 device driver—by placing a DEVICE = command 
in the configuration file. OS/2, however, keeps MS-DOS and OS/2 device 
drivers in separate lists. 














































Writing a 
Protected Mode 
Application 


CHAPTER 


Chapter 2 explored many of the basic concepts of programming under 
OS/2 and summarized most of the new features of the OS/2 develop¬ 
ment environment. This chapter presents the specific step-by-step pro¬ 
cedures for writing simple protected mode applications and for 
converting MS-DOS programs to run under the protected mode of 
OS/2. The type of programs discussed here are known as kernel appli¬ 
cations’, these are character-based applications that are not written 
specifically for the Presentation Manager. Furthermore, the programs 
in this chapter do not use advanced features of OS/2, such as multi¬ 
tasking or interprocess communication. Writing this type of program 
represents the second level of commitment to OS/2 (the first level is 
writing MS-DOS programs that can run in the compatibility environ¬ 
ment, described in Chapter 3). These programs are similar to MS- 
DOS programs, except that they run within a protected mode screen 
group of OS/2; they are typically applications that have been ported 
directly from MS-DOS. 
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If the simple OS/2 kernel applications described in this chapter are func¬ 
tionally equivalent to MS-DOS programs, what is the purpose of develop¬ 
ing them? There are two important reasons. First, the OS/2 user can load 
several of these protected mode applications and run them simultaneously 
with complete security. Second, writing a kernel application is a convenient 
first step toward a total conversion to OS/2. An MS-DOS application can be 
quickly transformed to a protected mode kernel application; then, the program 
can be gradually enhanced to take advantage of such features as the large 
virtual memory space, multitasking, interprocess communication, and the 
sophisticated services of the OS/2 application program interface. The pro¬ 
gram could also be enhanced to take advantage of the features of the Pre¬ 
sentation Manager. 

The chapter begins by outlining the basic steps for developing a kernel 
application using the C language. The next section focuses on the process 
for converting an MS-DOS program to the protected mode of OS/2, and 
provides an extensive chart showing the OS/2 functions that are equivalent 
to each of the MS-DOS and BIOS services. The following two sections 
show how an OS/2 program can attain a high level of device control by 
sending commands directly to device drivers, and by using special privileged 
routines that can perform direct device I/O. Following these two sections is 
a description of how to obtain greater control over the structure of your 
program by using a linker definition file. The next section discusses guide¬ 
lines for writing OS/2 background programs and for converting MS-DOS 
memory-resident programs to the protected mode of OS/2. The chapter 
concludes with a summary of the system files that are used in the develop¬ 
ment process. 


Figure 4.1 illustrates the four basic steps for using a high-level language to 
develop and run a simple protected mode program that calls one or more 
operating-system services. Briefly, these steps are as follows: 

1. Include the appropriate system header file(s) in your program. 

2. Compile the source code into protected mode object code. 

3. Link the object code with the system import library (DOS- 
CALLS.LIB). 

4. Load and run the program together with the dynamic-link 
library file(s). 
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1 INCLUDE HEADERS 


2 COMPILE 


[~3~ LINK 



LOAD & RUN 



FIGURE 4.1: Basic steps for developing a simple protected mode program 


These basic steps are illustrated through an OS/2 version of the arche¬ 
typal “hello world” C program, which is listed in Figure 4.2. Note that the 
examples and header files apply specifically to the C language; the general 
principles apply, however, to any high-level language compiler that supports 
OS/2. For more background information on such topics as the use of 
the OS/2 application program interface and the dynamic-link mechanism, 
see the appropriate sections of Chapter 2. 


Include Header Files 

As mentioned in Chapter 2, the only header file you need to include in your 
program is OS2.H. By default, this header file includes a minimal set of com¬ 
mon definitions. If you require additional definitions, you can force their inclu¬ 
sion by defining one or more appropriate constants before including OS2.H. 
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/* 

Figure 4.2 

This listing is an OS/2 version of the archetypal "hello world" 
program that serves to illustrate the basic steps for developing a 
simple protected mode program under OS/2. You can prepare this program 
using the following command lines 

cl /G2 /Zp /Lp fig4_2.c 

*/ 

#define INCL_SUB 
#include <os2.h> 

void main () 

{ 

VioWrtTTy 

("hello world\n", 

12 , 

0 ); 

} /* end main */ 


FIGURE 4.2: An OS/2 version of the archetypal “hello world” Cprogram 

See the section on the Application Program Interface in Chapter 2, and also the 
documentation provided with your compiler or the Programmer’s Toolkit for 
details on including the required header definitions. 

As mentioned in Chapter 2, OS/2 functions return an error status code 
in register AX; a return value of 0 indicates that the operation was success¬ 
ful, and a nonzero value is a code for a specific error condition. All codes 
refer to a single, standard table of OS/2 errors (unlike the MS-DOS version 
1.0 services, which used different error codes for different functions). You 
can include constant definitions for error codes by defining the constant 
INCL_DOSERRORS before including OS2.H; you are then free to use 
these descriptive constant identifiers rather than literal numbers in your 
error-handling routines. The example program in Figure 4.3 (discussed later 
in this chapter) illustrates the use of constant definitions for error process¬ 
ing. Also, the topic of error handling under OS/2 is treated in Chapter 8. 

Compile the Program 

The next step is to compile the program using a compiler designed to gener¬ 
ate protected mode code for OS/2. The following command compiles the 
example program of Figure 4.2 using the Microsoft C compiler, version 5.1. 
This version of the Microsoft compiler is designed to run in either real or 
protected mode, and to generate code for either MS-DOS or OS/2. 

cl /c /G2 /Zp /Lp fig4_2.c 


/* String to write. */ 
/* String length. */ 
/* Video handles must be 0. */ 
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The flags included with this command are typical of those used for generat¬ 
ing programs for the protected mode of OS/2, and they have the following 
meanings: 

/c This flag tells the compiler to generate an object file without running 
the linker (the default action of the CL command is to compile and 
link the program). 

/G2 This flag allows the compiler to generate instructions that are unique 
to the 80286 processor. Since a protected mode program must run on 
the 80286 or later model processor, it makes sense to take advantage 
of the advanced instructions provided by these processors. Do not use 
this flag, however, if you are developing a dual-mode program, as 
described in Chapter 5. 

/Zp This flag forces the compiler to pack all structures, meaning that each 
field of a structure is located at the first available byte address. By 
default, the C compiler aligns all structure members except char and 
unsigned char on word boundaries. However, the structures you 
declare for exchanging information with the OS/2 API must be 
packed, and therefore it is important to specify the /Zp option for 
programs that call these services. 

/Lp This flag causes the CL command to generate an object file to run in 
the protected mode of OS/2. To produce code for running in the real 
mode of MS-DOS or OS/2, use the /Lr or /Lc (compatible) flag. 

Link the Program 

The following command line links the example program of Figure 4.2 using 
the version of the linker supplied with Microsoft OS/2 languages or the 
Programmer’s Toolkit: 

link /NOI /NOD fig4_2.obj„,slibcep.lib doscalls.lib; 

The /NOI (“no ignore case”) option tells the linker to distinguish between 
uppercase and lowercase letters in names. This option is useful with a case- 
sensitive language such as C if you use identifiers that differ only by the case 
of one or more letters. The /NOD option instructs the linker not to search 
the default libraries specified in the object file. Although this command line 
looks much like one that could be used with the standard MS-DOS linker, it 
illustrates three important new features of the OS/2 linker and C compiler: 

* The OS/2 C compiler (specifically, version 5.1) supplies two ver¬ 
sions of the standard C library: one that can be called by real 
mode programs and one that can be called by protected mode 




Programmer’s 
Guide to OS/2 
CH4 


programs. The combined library (that is, the one containing 
floating-point emulation functions) for the real mode is normally 
named xLIBCER.LIB, where x is the first letter of the memory 
model. The protected mode version of the library is generally 
named xLIBCEP.LIB. The default C library, searched automati¬ 
cally by the linker, is named xLIBCE.LIB; however, if you are 
developing both real mode and protected mode programs, this 
library is generally replaced by the two mode-specific libraries. In 
this case, you must defeat the default library search and explicitly 
name the appropriate library. (Note that the C compiler also sup¬ 
plies a special C library for multiple-thread applications and one 
for generating a dynamic-link library version.) 

♦ You must also specify the import library, DOSCALLS.LIB. As 
explained in the section on dynamic linking in Chapter 2, this library 
resolves all references to OS/2 functions not by supplying the actual 
code, but by providing definition records that contain the name of a 
dynamic-link library file, and the entry point of the function within 
this library At run-time, OS/2 loads the dynamic-link library and 
supplies the actual addresses for all system functions that are called. 
(Note that for a protected mode program, DOSCALLS.LIB is also 
searched by default. However, in this example default searches are 
disabled and therefore this library must be explicitly named on the 
command line. Alternatively, you could defeat default searches 
specifically for SLIBCE.LIB by replacing the /NOD option with 
/NOD:SLIBCE.LIB. This is a new linker option. 

♦ The command line is terminated with a semicolon, since this ver¬ 
sion of the linker takes an additional parameter, which is omitted 
here. The additional parameter gives the name of a module defini¬ 
tion file (.DEF file), which will be explained later in this chapter. 

Note that the OS/2 linker will automatically produce an .EXE program 
file designed to run in protected mode if it encounters either an import 
library (such as DOSCALLS.LIB) or a module definition file (which does 
not contain the LIBRARY statement, explained later in the chapter). 

Load and Run the Program 

The final step is to load and run the program in a protected mode screen 
group. The primary requirement is that all dynamic-link libraries refer¬ 
enced by the program be located in the root directory of the boot disk, or in 
the directory specified by the LIBPATH configuration command. 
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Dynamic-link libraries have the extension .DLL, and it is convenient to 
keep them all in the same subdirectory (such as \OS2\LIB). Although the 
OS/2 services use only one import library file, they employ many dynamic- 
link libraries, having names such as DOSCALLl.DLL, KBDCALLS.DLL, 
and QUECALLS.DLL. 

Using the CL Driver and the MAKE Utility 

To distinguish all four of the basic steps for preparing a protected mode 
application, the CL command was used only to compile the program. For a 
simple application, however, the CL command is normally used to run both 
the compiler and the linker. In the example above, if the /c switch were left 
out of the command, CL would first compile FIG4_2.C and then automati¬ 
cally run the linker, specifying the appropriate libraries for the small model 
and the protected mode. 

Applications that consist of more than one source file are best developed 
with the help of a MAKE utility. This utility automates the process of run¬ 
ning the compiler and linker, and performs only those steps that are neces¬ 
sary to produce an up-to-date version of the program. Figures 4.3, 4.4, and 
4.5 demonstrate the steps for developing a protected mode program that 
consists of more than one source file. These figures also illustrate the use of 
the Microsoft MAKE utility. Figure 4.3 contains the main function for a 
protected mode program that uses the OS/2 API to obtain the volume label 
for a specified drive, and the date and time the volume label was created. 
The syntax for using this program is as follows: 

FIG4_3 [d] 

where d is the letter of the desired drive; if d is omitted, the default drive 
is used. 


/* 

Figure 4.3 

A protected mode program that displays the volume label, and the date 
and time it was created, for the specified drive. The syntax is 
FIG4_3 [d] 

where d is the letter of the desired drive. If d is omitted, the 
current drive is used. 

Prepare this program using the MAKE file: FIG4_5.MAK. 

*/ 

♦define INCL_DOSERRORS 
#include <os2.h> 


FIGURE 4.3: A protected mode program that obtains information on a volume label 
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#include <stdio.h> 

#include <ctype.h> 

extern void ErrorQuit (char *); 

struct 

{ 

unsigned Date; 
unsigned Time; 
unsigned char LabelLength; 
char Label [12]; 

> 

InfoStruct; 


/* C library include files. */ 

/* Contained in the file FIG4_4.C */ 

/* DosQFSInfo uses this structure to */ 

/* return volume label information. */ 

/* Label modification date. */ 

/* Label modification time. */ 

/* Length of volume label. */ 

/* The volume label itself. */ 


void main (int argc, char *argv[]) 

{ 

unsigned int DriveNumber; 
int ErrorCode; 
char Buf [11]; 


switch (argc) 

{ 

case Is 

DriveNumber =0; /* 0 indicates the default drive, 

break; 

case 2s /* Convert drive letter to number. 

DriveNumber = toupper (argv [1 ] [0]) - 64; 
break; 
default s 

ErrorQuit ("Invalid number of arguments.\n"); 
break; 


} 

ErrorCode = DosQFSInfo 

(DriveNumber, 

2 , 

(char *)&InfoStruct, 
sizeof (InfoStruct)); 
switch (ErrorCode) 

{ 


/* The drive number. 

/* Information level. 

/* Buffer to receive info. 
/* Length of buffer. 


case NO_ERROR s 
break; 

case ERROR_INVALID_DRIVEs 

ErrorQuit ("Invalid drive specification\n"); 
break; 


case ERROR_NO_VOLUME_LABELs 

ErrorQuit ("No volume label found.\n"); 
break; 
default s 

ErrorQuit ("Error finding volume label.\n"); 
break; 


} 

printf ("Volume label is %s\n",InfoStruct.Label); 
printf ("Data of creation is %02d/%02d/%04d\n", 

(InfoStruct.Date & OxOleO) >> 5, 

InfoStruct.Date & OxOOlf, 

((InfoStruct.Date & OxfeOO) >> 9) + 1980); 
printf ("Time of creation is %02ds%02d\n", 

(InfoStruct.Time & 0xf800) >> 11, 

(InfoStruct.Time & 0x07e0) >> 5); 


*/ 

*/ 


* 

* 

* 

* 


} /* end main */ 


FIGURE 4.3: A protected mode program that obtains information on a volume label (continued) 
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/* 

Figure 4.4 

This file contains the function ’ErrorQuit' that is called by the 
program of Figure 4.3. 

*/ 

♦define INCL_SUB 
#include <os2.h> 

#include <string.h> 

void ErrorQuit (char *Message) 

VioWrtTTy (Message,strlen (Message),0); 

DosExit 

(1, /* Terminate all threads. */ 

1); /* Result code to return to parent. */ 

} /* end ErrorQuit */ 


FIGURE 4.4: A C function called by the program of Figure 4.3 


# Figure 4.5 ... 

# This MAKE file prepares the protected mode program listed in 

# Figures 4.3 and 4.4. 

fig4_3.obj : fig4_3.c 

cl /c /G2 /Zp /Lp fig4_3.c 

fig4_4.obj s fig4_4.c 

cl /c /G2 /Zp /Lp fig4_4.c 

test.exe s fig4 3.obj fig4_4.obj 

link /NOI 7 nod fig4_3.obj fig4_4.obj,,,doscalls.lib slibcep.lib; 

FIGURE 4.5: A MAKE file for building the program of Figures 4.3 and 4.4 

The main function in Figure 4.3 calls the OS/2 function DosQFSInfo to 
obtain volume label information. The first parameter passed to this func¬ 
tion is the number of the desired drive, where 0 is the default drive, 1 is drive 
A, and so on. The second parameter specifies the level of information 
desired; the value 2 designates volume label information. The third parame¬ 
ter is the address of the buffer into which OS/2 loads the desired informa¬ 
tion, and the last parameter is the length of this buffer. The program passes 
the address and length of the structure InfoStruct. Using a structure rather 
than a simple array to receive information makes it simple to retrieve the 
individual information fields; note, however, that this structure must be 
packed, and hence the program is compiled with the /Zp flag. This pro¬ 
gram includes the appropriate definitions for the DosQFSInfo function by 
including the file OS2.H. Since this program also makes use of constant 
identifiers for error codes, it incorporates the definitions for these constants 
by defining the constant INCL_DOSERRORS before including OS2.H. 
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If an error is encountered, the program calls the utility function Error- 
Quit, which is in the separate source file listed in Figure 4.4. ErrorQuit per¬ 
forms two simple tasks. First, it uses the OS/2 video subsystem call 
VioWrtTTy to print the error message that was passed as a parameter. This 
function prints a string at the current cursor position; the first parameter is 
the address of the string, the second parameter the length of the string, and 
the last parameter is the Vio handle, which must be 0. Second, ErrorQuit 
uses the OS/2 kernel function DosExit to terminate the current process. 
The first parameter to this function is an action code, where 0 requests ter¬ 
mination of only the current thread, and 1 requests termination of all 
threads in the process. ErrorQuit passes the value 1 to terminate the entire 
process. The second parameter is the result code, which is the value 
returned to the parent process (normally the command interpreter). Error- 
Quit returns a value of 1 to indicate an error condition (0 typically indicates 
that the program was successful, and a nonzero value indicates some error 
condition). 

Note that in the function ErrorQuit it would have been just as effective 
to use the standard C library functions printf and exit rather than the direct 
calls to the operating-system services VioWrtTTy and DosExit; the Micro¬ 
soft C library for the protected mode of OS/2 supplies almost all of the 
functions found in the MS-DOS version of the library (notable exceptions 
are described in the next section). In general, however, you can achieve 
greater control and a higher level of efficiency by calling the operating sys¬ 
tem directly rather than routing your request through the C library (which 
ultimately calls OS/2 itself). Also, the OS/2 API supplies numerous serv¬ 
ices not offered through the C library, such as functions for the multitasking 
of threads, interprocess communication, managing the screen, and many 
others. The cost of using calls to OS/2 within a C program is loss of imme¬ 
diate portability to other operating systems. 

Figure 4.5 provides a MAKE file for preparing the program in Figures 
4.3 and 4.4. This program specifies the same set of flags that are used to 
process the example program of Figure 4.2, and it will compile only a pro¬ 
gram that has been modified since the last time the MAKE file was run. See 
the Microsoft utilities handbook for more information on using MAKE. 


CONVERTING 
AN MS-DOS 
PROGRAM TO 
THE OS/2 
PROTECTED 
MODE 


This section describes the first step toward converting an MS-DOS applica¬ 
tion to OS/2: modifying the source code where necessary and recompiling 
the program under the OS/2 version of the C compiler. Once this process is 
complete, the program will run in a protected mode screen group and will 
function just as it functions under MS-DOS. The next stage of the conver¬ 
sion process is to enhance the application to take advantage of the advanced 
features of OS/2; this second stage is the topic of Parts Three to Five. 
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This section focuses on the conversion of MS-DOS programs written in 
the C language (specifically Microsoft C). The C compiler automatically 
handles many of the details of writing code compatible with the protected 
mode, and it masks many of the differences between MS-DOS and OS/2. 
Also, the C language inherently enforces most of the rules for programming 
under a protected mode operating system, such as maintaining distinct code 
and data segments. If you are using another high-level language compiler 
that supports OS/2, the basic development process is the same and the gen¬ 
eral principles discussed in this section still apply. See Chapter 2 for a discus¬ 
sion of both the basic rules for developing protected mode applications, and 
the underlying differences between MS-DOS and OS/2, especially if you 
are writing assembly language routines. 

The simplest type of C program to convert is one that uses the standard 
C library function calls and performs no low-level operations. Such a pro¬ 
gram could be readily recompiled under the OS/2 version of the C compiler 
and would immediately run in a protected mode screen group. These pro¬ 
grams, however, are rare. To gain efficiency and take advantage of the 
resources present in MS-DOS machines, most real-mode C applications 
contain low-level routines and operating-system-specific code that must be 
modified to allow the program to run under the protected mode of OS/2. 

The following are some of the general categories of instructions or oper¬ 
ations that may need to be modified to convert a C program written for MS- 
DOS to an OS/2 protected mode application: 

♦ Invoking MS-DOS interrupt services 

♦ Invoking BIOS interrupt services 

❖ Invoking interrupt 13h mouse driver services 

♦ Intercepting interrupt vectors 

❖ Reading or writing to specific memory locations outside 
the program 

* Reading or writing to 1/O ports 

For each of these categories, this section describes the specific operations 
that are prohibited, and suggests equivalent or alternative methods that can 
be used under OS/2. Many MS-DOS programs written in Microsoft C per¬ 
form operations in one or more of these categories through standard C con¬ 
structs (such as using far pointers to access system memory), through C 
library functions (such as intdos or inp), or through assembly language 
subroutines. The last part of the section lists the C library functions that are 
not provided by the protected mode version of the library, and lists pro¬ 
tected mode methods you may substitute for these functions. 
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MS-DOS Services 

Many real-mode C programs request the services of the MS-DOS operating 
system through the software interrupt mechanism. Microsoft C does not 
have an instruction that directly generates an interrupt operation, nor does 
it have a direct means for loading machine registers (the system interrupt 
services generally exchange information with the calling program through 
registers). However, real-mode C programs can indirectly issue software 
interrupts through one of two methods. First, a real mode program can 
be linked with an assembly language subroutine that loads the machine 
registers and issues an INT n machine instruction, where n is the number 
of the desired interrupt. Second, the real-mode C library contains the 
following interrupt interface functions that load the specified values into 
registers, issue the requested interrupt, and then return the register values to 
the program: 

♦ Mgs 

♦ int86 

♦ int86x 

♦ intdos 

♦ intdosx 

As explained in Chapter 2, the OS/2 API services are accessed through 
direct calls to dynamic-link library routines, and not through the interrupt 
mechanism. In fact, OS/2 protected mode programs are prohibited from 
issuing software interrupts. Table 4.1 lists the MS-DOS interrupts and the 
nearest equivalent OS/2 API services. Table 4.2 provides similar informa- 
tion for each of the MS-DOS functions that are accessed through interrupt 
21h, the main MS-DOS function dispatcher. 

In general, you can simply replace an interrupt service request with the 
equivalent call to the OS/2 API. Note, however, that for certain services 
provided by MS-DOS, as well as by the BIOS (discussed in the next section), 
there are no closely equivalent OS/2 functions. For these routines, one of 
the following three approaches may allow you to generate comparable code 
for the protected mode: 

♦ Redesign the code to employ the API functions that are provided. 
Some of the entries in Tables 4.1, 4.2, and 4.3 suggest related 
routines. 
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MS-DOS 

Interrupt 

V 

Description 

▼ 

OS/2 API Equivalent 
▼ 

20h 

Terminate program 

DosExit 

21h 

Main function dispatcher 

See Table 4.2 

25h 

Absolute disk read 

None; DosDevIOCtl 
(08h/64h)* 

26h 

Absolute disk write 

None; DosDevIOCtl 
(08h/44h)* 

27h 

Terminate but stay resident 

None; see DosExit 

2Fh 

Access PRINT queue 

None; PRINT not resident 

*08h is the category number, and 64h and 44h are the function numbers. 


TABLE 4.1: MS-DOS Interrupts and the Equivalent OS/2 API Functions 


Function 

Description 

OS/2 Equivalent 




OOh 

Terminate program 

DosExit 

Olh 

Keyboard input 

KbdCharln 

02h 

Display output 

VioWrtTTy 

03h 

Auxiliary input 

DosRead 

04h 

Auxiliary output 

DosWrite 

05h 

Printer output 

Dos Write 

06h 

Direct console I/O 

KbdCharln, VioWrtTTy 

07h 

Direct console I/O without 
echo 

KbdCharln 

08h 

Console I/O without echo 

KbdCharln 

09h 

Print string 

VioWrtTTy 


TABLE 4.2: MS-DOS Interrupt 21 h Services and the Equivalent OS/2 API Functions 
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Function 

▼ 

Description 

▼ 

OS/2 Equivalent 

V 

OAh 

Buffered keyboard input 

KbdStringln 

OBh 

Check standard input status 

KbdPeek 

OCh 

Clear keyboard buffer, etc. 

KbdFlushBuffer, 

KbdCharln 

ODh 

Disk reset 

DosBufReset 

OEh 

Select disk 

DosSelectDisk 

OFh 

Open file 

DosOpen 

lOh 

Close file 

DosClose 

llh 

Search for first entry 

DosFindFirst 

12h 

Search for next entry 

DosFindNext 

13h 

Delete file 

DosDelete 

14h 

Sequential read 

DosRead 

15h 

Sequential write 

DosWrite 

16h 

Create file 

DosOpen 

17h 

Rename file 

DosMove 

19h 

Get current drive 

DosQCurDisk 

lAh 

Set disk transfer address 

None 

lBh 

Allocation information for 
default drive 

DosQFSInfo 

ICh 

Allocation information for 
given drive 

DosQFSInfo 

21h 

Random read 

DosRead 

22h 

Random v/rite 

DosWrite 

23h 

File size 

DosQFilelnfo 

24h 

Set relative record field 

BosChgFilePtr 


TABLE 4.2: MS-DOS Interrupt 21 h Services and the Equivalent OS/2 API Functions 
(continued) 
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Function 

Description 

▼ 

OS/2 Equivalent 

25h 

Set interrupt vector 

None; see DosSetVec 

26h 

Create new program segment 

None; see DosExecPgm 

27h 

Random block read 

DosRead 

28h 

Random block write 

DosWrite 

29h 

Parse file name 

None 

2Ah 

Get date 

OosGetDateTime 

2Bh 

Set date 

DosSetDateTime 

2Ch 

Get time 

OosGetDateTime 

2Dh 

Set time 

DosSetDateTime 

2Eh 

Set/reset verify switch 

DosSetVerify 

2Fh 

Get disk transfer address 

None 

3 Oh 

Get DOS version number 

Dos Get Version 

3 lh 

Terminate process/remain 
resident 

None 

33h 

Control-Break check 

None; see DosHoldSignal, 
DosSetSignalHandler, 
DosDevIOCtl 
(04h/51h,04h/71h)* 

35h 

Get vector 

None; see DosSetVec 

36h 

Get disk free space 

DosQFSInfo 

38h 

Get/set country-dependent 
information 

DosGetCtrylnfo 

39h 

Create subdirectory 

DosMkdir 

3 Ah 

Remove subdirectory 

DosRmdir 

3Bh 

Change current directory 

DosChdir 

3Ch 

Create a file 

DosOpen 


TABLE 4.2: MS-DOS Interrupt 21h Services and the Equivalent OS/2 API Functions 


(continued) 
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Function 

V 

Description 

▼ 

OS/2 Equivalent 

V 

3Bh 

Open a file 

DosOpen 

3Eh 

Close a file handle 

DosClose 

3Fh 

Read from a file or device 

DosRead 

40h 

Write to a file or device 

DosWrite 

41h 

Delete a file 

DosDelete 

42h 

Move file read/write pointer 

DosChgFilePtr 

43h 

Get or set file mode 

DosQFileMode, 

DosSetFileMode 

44h 

1/O control for devices 

DosDevIOCtl 

45h 

Duplicate a file handle 

DosDupHandle 

46h 

Force a duplicate of a file 
handle 

DosDupHandle 

47h 

Get current directory 

DosQCurDir 

48h 

Allocate memory 

DosAllocSeg 

49h 

Free allocated memory 

DosFreeSeg 

4Ah 

Modify allocated memory 
block 

DosReallocSeg 

4Bh 

Load or execute a program 

DosExecPgm 

4Ch 

Terminate a process 

DosExit 

4Dh 

Get return code of a 
subprocess 

DosCWait 

4Eh 

Find first matching file 

DosFindFirst 

4Fh 

Find next matching file 

DosFindNext 

54h 

Get verify setting 

DosQVerify 

56h 

Rename a file 

DosMove 


TABLE 4.2: MS-DOS Interrupt 21 h Services and the Equivalent OS/2 API Functions 
(continued) 
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Function Description OS/2 Equivalent 


T 

V 

V 

57h 

Get/set a file’s date and time 

DosQFilelnfo, 

DosSetFilelnfo 

59h 

Get extended error 

DosErrClass 

5Ah 

Create unique file 

None; see DosOpen 

5Bh 

Create new file 

DosOpen 

5Ch 

Lock/unlock file access 

DosFileLock 

62h 

Get PSP address 

None; see DosGetEnv, 
DosGetlnfoSeg 

65h 

Get extended country 
information 

DosGetCtrylnfo 

66h 

Get/set global code page 

DosGetCp, DosSetCp 

67h 

Set handle count 

DosSetMaxFH 

68h 

Commit file 

DosBufReset 

* 04h is the category number, and 5lh and 71h are the function numbers 


TABLE 4.2: MS-DOS Interrupt 21 h Services and the Equivalent OS/2 API Functions 
(continued) 

❖ Use direct device I/O control (through the OS/2 DosDevIOCtl 
function) to perform low-level, device-specific operations not sup¬ 
ported by the API. Some of the entries in Tables 4.1, 4.2, and 4.3 
list appropriate I/O control functions. The first number is the 
category and the second is the function ; I/O control is discussed 
later in the chapter. 

♦ Write low-level assembly language routines. These routines, which 
must generally be assigned special I/O privilege, are discussed later 
in the chapter. 

These three approaches are listed in order of decreasing conformance with 
the philosophy of OS/2. You should use the standard API whenever pos¬ 
sible, perform direct I/O control only when necessary, and write privileged 
assembly language routines solely as a last resort. 
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Service 


Description 

OS/2 Equivalent 

¥ 


¥ 

¥ 

INT 05h 

Print screen 

VioPrtSc; see also 
VioPrtScToggle 

INT lOh 

Video services; functions follow 



OOh 

Set video mode 

VioSetMode 


Olh 

Set cursor type 

VioSetCurType 


02h 

Set cursor position 

VioSetCurPos 


03h 

Read cursor position 
and type 

VioGetCurPos, 

VioGetCurType 


04h 

Read light-pen 
position 

None 


05h 

Select active display 
page 

None 


06h 

Scroll active page up 

VioScrollUp 


07h 

Scroll active page 
down 

VioScrollDn 


08h 

Read 

character / attr ib ute 

VioReadCellStr 


09h 

Write 

character/ attribute 

VioWrtNCell 


OAh 

Write character 

VioWrtNChar 


OBh 

Set color palette 

VioSetState 


OCh 

Write pixel 

None (text only) 


ODh 

Read pixel 

None (text only) 


OEh 

Write character in 
teletype mode 

VioWrtTTy 


OFh 

Get current video 
state 

VioGetMode 


lOh 

Set EGA palette 
registers 

VioSetState 


TABLE 4.3: The ROM BIOS Services and Equivalent OS/2 API Functions 
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Service 

▼ 


Description 

OS/2 Equivalent 


llh 

EGA character 
generator 

None 


12h 

EGA alternate select 

VioGetConfig (partial) 


13h 

Sub functions 1 & 2: 




Write string with 
single attribute 

VioWrtCharStrAtt 



Subfunctions 3 & 4: 




Write 

character / attribute 
string 

VioWrtCellStr 

INT llh 

List of installed equipment 

DosDevConfig 

INT 12h 

Memory size 

None; see DosMemAvail 

INT 13h 

Direct disk/diskette I/O; 
functions follow 



OOh 

Reset disk/diskette 
system 

None; see DosDevIOCtl 
(08h/20h) 


Olh 

Read disk/diskette 
status 

None 


02h 

Read sectors 

None; use DosDevIOCtl 
(08h/64h) 


03h 

Write sectors 

None; use DosDevIOCtl 
(08h/44h) 


04h 

Verify sectors 

None; use DosDevIOCtl 
(08h/65h) 


05h 

Format track 

None; use DosDevIOCtl 
(08h/45h) 

INT 14h 

Communications services; 
functions follow 



OOh 

Initialize 

communications port 

None; use DosDevIOCtl 
(00h/41h,42h) 


TABLE 4.3: The ROM BIOS Services and Equivalent OS/2 API Functions (continued) 
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Service 


Description 

OS/2 Equivalent 

V 


w 



Olh 

Write to 

communications port 

DosWrite 


02h 

Read 

communications port 

DosRead 


03h 

Return 

communication port 
status 

None; use DosDevIOCtl 
(00h/65h,67h) 

INT 16h 

Keyboard services; functions 
follow 



OOh 

Read character from 
keyboard 

KbdCharln 


Olh 

Test if character is 
ready 

KbdPeek 


02h 

Return current shift 
status 

KbdGetStatus 


03h 

Set keyboard repeat 
rate 

None; use DosDevIOCtl 
(04h/54h) 


04h 

Keyboard click 
adjustment 

None 


05 h 

Stuff keyboard buffer 

None; use a monitor 
(Chapter 12) 

INT 17h 

Printer services; functions 
follow 



OOh 

Print character 

DosWrite 


Olh 

Initialize the printer 
port 

None; use DosDevIOCtl 
(05h/46h) 


02h 

Read printer status 

None; use DosDevIOCtl 
(05h/65h) 

INT 18h 

Load ROM BASIC 

None 

INT 19h 

Bootstrap loader 

None 


TABLE 4.3: The ROM BIOS Services and Equivalent OS/2 API Functions (continued) 
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Service 


Description 

▼ 

OS/2 Equivalent 

INT lAh 

Time-of-day services; functions 
follow 



OOh 

Read clock count 

None; see DosGetDateTime, 
DosGetlnfoSeg, DosTimer... 


Olh 

Set clock count 

None; see DosSetDateTime 


02h 

Read real-time clock 

DosGetDateTime 


03h 

Set real-time clock 

DosSetDateTime 


Q4h 

Read date from 
real-time clock 

DosGetDateTime 


05h 

Set date for real-time 
clock 

DosSetDateTime 


06h 

Set alarm 

None; see DosTimerAsync, 
DosTimerStart 


07h 

Reset alarm 

None; see DosTimerStop 

Note-. The references to DosDevIOCtl functions are in the form c/f, where c 
is the category number and/is the function number. 


TABLE 4.3: The ROM BIOS Services and Equivalent OS/2 API Functions (continued) 


BIOS Services 

Many MS-DOS programs also access the services of the ROM BIOS 
through software interrupts. These services are especially valuable for effi¬ 
ciently accessing low-level machine resources. For example, BIOS interrupt 
lOh offers a wealth of services for controlling the screen and producing 
video output. However, not only are protected mode programs prohibited 
from issuing interrupt instructions, but even if they could generate inter¬ 
rupts, the ROM BIOS code cannot run in the protected mode. 

Fortunately, the OS/2 API provides equivalent services for most of the 
BIOS interrupt functions (some of which are more efficient than their BIOS 
counterparts). Table 4.3 lists the commonly used BIOS service routines and 
the nearest equivalent OS/2 API functions. Most BIOS service requests 
may simply be replaced with the equivalent API function; see the comments 
in the previous section for the strategies you may use to replace functions 
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that have no close API equivalents. Note that many of the low-level opera¬ 
tions performed under MS-DOS through the BIOS can be accomplished 
under OS/2 by passing commands directly to the device driver through the 
DosDevIOCtl command; Table 4.3 supplies the category and function 
numbers for these commands. See the section on I/O control later in 
this chapter. 


Mouse Services 

Table 4.4 lists the MS-DOS mouse driver functions that are accessed 
through interrupt 33h, and the most nearly equivalent OS/2 API function 
calls. The OS/2 mouse subsystem calls, which all begin with the preface 
Mou , require that the user install the correct mouse driver through the con¬ 
figuration file DEVICE = command. 


Intercepting interrupt Vectors 

As mentioned in Chapter 2 (in the section on restricted segment access), an 
OS/2 protected mode program is prohibited from directly intercepting 
either hardware or software interrupt instructions. All hardware interrupts 
originating from within the processor, or from external devices, transfer 
control to code within the kernel; the operating system can then pass con¬ 
trol to a program that has registered an interrupt-handling routine. Device 
drivers can register handlers for interrupts originating from external 
devices. Application programs, however, can register handlers only for one 
of the following interrupts that are generated by internal processor 
exceptions: 


INTERRUPT EXCEPTION 


0 Divide error 

4 Overflow 

5 Bound violation 

6 Invalid opcode 

7 Processor extension not 
available 

16 Processor extension error 


You must therefore eliminate all other hardware and software interrupt¬ 
handling routines from code that is to be converted to run in the protected 
mode. 
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Function 

Description 

OS/2 API Equivalent 

Y 

V 

Y 

00h 

Install flag and reset 

MouOpen 

Olh 

Show pointer 

MouDrawPtr 

02h 

Hide pointer 

MouRemovePtr 

03h 

Get position and button status 

MouGetPtrPos, 

MouReadEventQue 

04h 

Set pointer position 

MouSetPrtPos 

05h 

Get button press information 

MouReadEventQue 

06h 

Get button release information 

MouReadEventQue 

07h 

Set min and max horizontal 
position 

None 

08h 

Set min and max vertical 
position 

None 

09h 

Set graphics pointer block 

MouSetPtrShape 

OAh 

Set text pointer 

MouSetPtrShape 

OBh 

Read mouse motion counters 

None; see 

MouReadEventQue 

OCh 

Set user-defined subroutine 

MouSetEventMask 

ODh 

Light-pen emulation on 

None 

OEh 

Light-pen emulation off 

None 

OFh 

Set mickey/pixel ratio 

MouSetScaleFact 


TABLE 4.4: MS-DOS Interrupt 33h Mouse Functions and OS/2 Equivalents 


Accessing Absolute Memory Addresses 

As mentioned in the section in Chapter 2 on protection, an OS/2 applica¬ 
tion is not free to read or write to arbitrary memory locations. In general, 
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the only segments an OS/2 program can access are in one of the following 
three categories: 

♦ Segments that the process owns exclusively and that have the 
proper permissions 

♦ Segments explicitly defined to be shared among two or more 
processes 

♦ Global segments that a process is allowed to read, such as the sys¬ 
tem information segment accessed through the DosGetlnfoSeg 
function 

Many MS-DOS applications freely read or write to memory locations 
outside the program area. A C program typically accesses these memory 
addresses through far pointers or through assembly language subroutines. 
To convert an MS-DOS program to run in the protected mode of OS/2, you 
must eliminate all illicit memory accesses; attempts to access these locations 
in the protected mode will result in a protection violation and cause the 
operating system to abort the current process. This section discusses the fol¬ 
lowing three types of far memory accesses common to MS-DOS programs, 
and suggests alternative methods compatible with OS/2: 

♦ Reading or writing to the BIOS data area in low memory 

♦ Exchanging information with other programs through common 
areas of memory 

♦ Directly accessing video memory to achieve fast screen output 

BIOS Data Area 

Many MS-DOS programs read the data stored by the BIOS beginning at 
absolute address 0040h:0000h. Some programs also write to this area to 
modify the subsequent behavior of the BIOS and other programs. Chapter 
2, in the section on the BIOS level, describes the most important items of 
information stored in the BIOS data area. Under OS/2, you must replace 
these direct memory accesses with appropriate calls to the API. Fortu¬ 
nately, the OS/2 API provides a wealth of information-returning func¬ 
tions; these functions are described in Chapter 2 (in the section on program 
entry conditions). 


Communication Areas 

MS-DOS reserves a 16-byte block of memory beginning at address 
0040h:00F0h for communication among applications. OS/2 protected 
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mode applications, however, must not access this or other arbitrary mem¬ 
ory locations for the sake of exchanging data with other programs. Rather, 
these applications should take advantage of the extensive interprocess com¬ 
munication facilities provided by OS/2, which are discussed in Chapter 7. 

Video Memory 

OS/2 provides a much more comprehensive and efficient set of functions 
for generating screen output than those available under MS-DOS. Accord¬ 
ingly, MS-DOS text mode programs that perform screen output by writing 
directly to video memory should be converted to use the OS/2 video subsys¬ 
tem functions (the Vio services). An added benefit of routing video output 
through OS/2 is that the resulting program will be able to run within a win¬ 
dow of the Presentation Manager. Bypassing the operating system and 
directly accessing physical devices is also contrary t o the general philosophy 
of OS/2. 

However, to accommodate graphics programs that do not use the Pre¬ 
sentation Manager graphics API, and other MS-DOS-style applications, 
OS/2 allows programs to directly manipulate video memory through either 
of the following mechanisms: 

<► A program can write text or graphics data to a logical buffer, 
which is subsequently used to update the physical screen. 

* A program can obtain the address of the physical video buffer and 
directly write to this area, in the same manner as many MS-DOS 
applications. 

Note that programs using either of these two methods must follow a spe¬ 
cial set of procedures, which are described in Chapter 9. 

Direct Port i/0 

Direct reads or writes to I/O ports constitute the final category of opera¬ 
tions that need to be eliminated or modified when a program is converted to 
OS/2. In assembly language, port I/O is accomplished through the follow¬ 
ing instructions: 

* IN 

♦ INS 

♦ OUT 
<• OUTS 
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USING DIRECT 

DEVICE 

CONTROL 


The following functions in the MS-DOS version of the Microsoft C library 
also perform direct port I/O: 

♦ inp 

♦ inpw 

♦ ©utp 

♦ ©lltpw 

When converting an MS-DOS program that contains direct port reads or 
writes, the ideal strategy is to perform device I/O through the standard 
OS/2 API. If the required functions are not available, a second option is to 
send control commands directly to the appropriate device driver through 
the OS/2 DosDevIOCtl command (discussed in the next section). As a last 
resort, OS/2 allows you to write //Oprivileged routines that may use direct 
port I/O. These routines must meet a stringent set of requirements that are 
discussed in the section on I/O privileged routines, later in this chapter. 

Note also that protected mode applications are prohibited from enabling 
or disabling hardware interrupts through the STI and CLI assembly lan¬ 
guage instructions or the _enab!e and _disable functions provided by the 
Microsoft C compiler version 5.0. I/O privileged routines, however, are 
also allowed to use these two instructions. See also the discussion on 
restricted instructions in Chapter 2. 

C Library Changes 

A protected mode C program can safely call the functions in the protected 
mode version of the standard C library, since these functions have been 
properly converted for OS/2. However, because of the protected mode pro¬ 
gramming constraints discussed in the preceding sections and in Chapter 2, 
certain C library functions that are provided by Microsoft C version 5.0 are 
not supplied in the protected mode library versions. Table 4.5 lists the 
library functions not available for the protected mode, and suggests alter¬ 
native methods compatible with the protected mode. 


In the same manner as MS-DOS, all physical devices under OS/2 are 
accessed uniformly through the file system. I/O operations to a physical 
device such as a serial port are performed through the same basic sequence 
of steps used to accomplish I/O to disk files. These steps are as follows: 

1. Open the file or device by calling DosOpen, passing this function 
the appropriate file or device name. 
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Library Function 

Purpose 

Alternative Method 

▼ 

V 

▼ 

bdos 

Invoke MS-DOS 
function 

See Table 4.2 

_bios_disk 

Access BIOS disk 
services 

See Table 4.3, interrupt 
13h 

_bios_equiplist 

Obtain list of installed 
equipment 

DosDevConfig 

_bios_keybrd 

Access BIOS keyboard 
services 

See Table 4.3, interrupt 
16h 

_bios_memsize 

Obtain amount of 
available memory 

None; see DosMemAvail 

_bios_jprinter 

Access BIOS printer 
services 

See Table 4.3, interrupt 
17h 

_bios_serialcom 

Access BIOS serial port 
services 

See Table 4.3, interrupt 
14h 

__bios__timeofday 

Access BIOS time-of-day 
services 

See Table 4.3, interrupt 
lAh 

_chain_intr 

Chain to an interrupt 
handler 

None 

_disable 

Disable hardware 
interrupts 

Use I/O privileged 
segment 

_dos_allocmem 

Allocate block of DOS 
memory 

E>osAllocSeg 

_clos_close 

Close file handle 

DosClose 

_clos_creat 

Create a file 

DosOpen 

_dos_creatnew 

Create a file if not 
existent 

D'osOpen 

_dos_findfirst 

Find file matching 
specifications 

DosFindFirst 

_dos_findnext 

Find next matching file 

DosFindNext 

_d.os_freemem 

Free block of DOS 
memory 

DosFreeSeg 


TABLE 4.5: C Library Functions Not Supplied with the Protected Mode Library 
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Library Function 

Purpose 

Alternative MethM 

V 


▼ 

dos getdate 

Obtain system date 

DosGetDateTime 

dosgetdiskfree 

Get disk free space 

DosQFSInfo 

_dos_getdrive 

Get current drive 

DosQCurDisk 

_dos_getfileattr 

Get file mode 

DosQFileMode 

_dos_getftime 

Get file date and time 

OosQFilelnfo 

_dos_gettime 

Get system time 

DosGetDateTime 

_dos_getvect 

Get interrupt vector 

None; see DosSetVec 

_dos_keep 

Terminate 
program/remain 
resident 

None 

_dos_open 

Open a file 

DosOpen 

_dos_read 

Read from a file or 
device 

DosRead 

_dos_setblock 

Modify allocated 
memory block 

DosReallocSeg 

_dos_setdate 

Set system date 

DosSetDateTime 

_dos_setdrive 

Set default drive 

DosSelectDisk 

_dos_setfileattr 

Set file mode 

DosSetFileMode 

_dos_setftime 

Set file modification 
time 

DosSetFilelnfo 

_dos_settime 

Set system time 

DosSetDateTime 

_dos_setvect 

Set interrupt vector 

None; see DosSetVec 

_dos_write 

Write to a file or device 

DosWrite 

dosexterr 

Get extended error 
information 

DosErrClass 


TABLE 4.5: C Library Functions Not Supplied with the Protected Mode Library 
(continued) 
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Library Function 

Purpose 

Alternative Method 

▼ 

¥ 

¥ 

_enable 

Enable hardware 
interrupts 

Use I/O privileged 
segment 

_harderr 

Set critical-error handler 

DosBrror 

_hardresume 

Return from error 
handler to DOS 

See DosError 

_hardretn 

Return from error 
handler to application 

See DosError 

inp 

Read byte from port 

Use I/O privileged 
segment 

inpw 

Read word from port 

Use I/O privileged 
segment 

int86 

Invoke software 
interrupt 

See Tables 4.1 to 4.4 

int86x 

Invoke software 
interrupt 

See Tables 4.1 to 4.4 

intdos 

Invoke MS-DOS 
function 

See Table 4.2 

intdosx 

Invoke MS-DOS 
function 

See Table 4.2 

outp 

Write byte to port 

Use I/O privileged 
segment 

outpw 

Write word to port 

Use I/O privileged 
segment 


TABU: 4.6: C Library Functions Not Supplied with the Protected Mode Library 
(continued) 


2. Save the handle returned by DosOpen. 

3. Perform I/O to the file or device by calling DosRead or DosWrite, 
passing these functions the proper handle. 

4. Close the file or device before program termination using Bos- 
Close. 
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Just as each file has a name, each device also has a unique name. Under 
OS/2, the following reserved names are used for the basic devices: 


NAME 

CLOCKS 
COM 1-COM4 
CON 
KBD$ 

LPT1-LPT3 

MOUSES 

NUL 

POINTERS 

PRN 

SCREENS 


DEVICE 

Real-time clock 

Serial ports 

Console 

Keyboard 

Parallel ports 

Mouse device 

Null device 

Mouse pointer 

Parallel port 
(= LPT1) 

Video screen 


When you pass a name to DosOpen, the operating system first determines 
whether the name refers to one of the above devices. If the name does not 
match one of these reserved names, then the system assumes it refers to a 
disk file. 

It is not always necessary to open a file handle explicitly before perform¬ 
ing device I/O; when a program begins executing, OS/2 automatically 
opens three standard handles. These handles, and the devices that are asso¬ 
ciated with them by default, are as follows: 


STANDARD DEFAULT 

HANDLE NAME DEVICE 

0000 Standard input Keyboard 

0001 Standard output Screen 

0002 Standard error Screen 


Note that unlike MS-DOS, OS/2 does not provide standard handles for the 
printer and serial port. An important feature of the standard preopened 
handles is that they can be redirected to other files or devices. The user can 
redirect any of these handles from the command line when running the pro¬ 
gram, and a parent process can redirect the standard handles inherited by a 
child process. Thus, the actual source or destination of data processed by 
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a program using the standard handles can be changed each time the pro¬ 
gram is run. See the OS/2 Programmer's Guide, the OS/2 User's Refer¬ 
ence, or the OS/2 Programmer's Learning Guide for more information on 
file redirection. 

In addition to this general device I/O interface, OS/2 also allows you to 
send device-specific control commands directly to the device driver through 
the DosDevIOCtl system call. These commands are known as generic I/O 
control commands . As seen in the previous sections, the standard OS/2 
API fails to provide some of the low-level device services available through 
the ROM BIOS under MS-DOS. You can perform many of these opera¬ 
tions, however, by sending control commands through the DosDevIOCtl 
function (without the need to use assembly language or the privileged seg¬ 
ments described in the next section). Although it is preferable to access 
devices whenever possible through standard API functions, such as 
DosRead and DosWrite, the low-level control commands you can issue 
through DosDevIOCtl can be especially useful when first converting an 
MS-DOS application to OS/2 (high-performance MS-DOS applications 
typically contain much low-level code). Tables 4.1 through 4.3 suggest Bos- 
DevIOCtl commands corresponding to many of the interrupt services avail¬ 
able under MS-DOS that are not provided by the OS/2 API. 

Since the generic I/O commands are device-specific, they are divided 
into groups known as categories , where each category of commands is suit¬ 
able for a specific type of device. A specific command within a given cate¬ 
gory is identified by a function number. The following are the basic 
categories defined by OS/2: 


CATEGORY 

DEVICE TYPE 

Olh 

Serial port 

03h 

Screen/mouse pointer 

04h 

Keyboard 

05h 

Printer 

06h 

Light pen 

07h 

Mouse 

08h 

Disk/diskette: logical 
drive 

09h 

Disk /diskette: physical 
device 

OAh 

Character monitor control 

QBh 

General device 
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Note that custom device drivers may supply user-defined categories of func¬ 
tions in addition to those defined by OS/2; the collection of generic I/O 
control commands is thus an extensible OS/2 resource. Note that the refer¬ 
ences to DosDevIOCtl functions in Tables 4.1 through 4.3 are in the form 
c//, where c is the category number and /is the function number. A list of 
the individual generic I/O control commands provided by OS/2, together 
with short descriptions, is given in Appendix C; see the OS/2 Programmer's 
Reference or the OS/2 Device Driver Guide for more detailed documenta¬ 
tion. 

Figure 4.6 lists a protected mode program that demonstrates the use of 
DosDevIOCtl to perform a device control service not provided by the OS/2 
API. Specifically, this program sets the repeat rate of the keyboard accord¬ 
ing to the parameters passed to the program from the command line (the 
default repeat rate of the PC AT keyboard is excruciatingly slow). The syn¬ 
tax for running the program is 

FIG4_6 d r 

where d is the delay in milliseconds (0 to 1000), and r is the repeat rate in charac¬ 
ters per second (1 to 30). The repeat rate is the rate that a keystroke is automati¬ 
cally repeated while the key is held down, and the delay is the pause before the 
automatic repetition begins. Note that on a PC AT running MS-DOS you can 
set the repeat rate through BIOS interrupt 16h, function Q3h. 

The program first converts the two parameters to numeric values and 
checks that these values are within appropriate ranges. It then performs the 


/* 

Figure 4.6 

This program demonstrates the use of the OS/2 function DosDevIOCtl to 
send a control command directly to a device. Specifically, the program 
causes the keyboard repeat rate to be altered according to the 
parameters that are passed from the command line. The syntax is 
FIG4_6 d r 

where d is the desired delay value in milliseconds (0 to 1000), and r is 
the repeat rate in characters per second (1 to 30). Prepare this program 
using the following command: 

cl /G2 /Zp /Lp fig4_6.c 

#define INCL_DOSDEVICES 
#include <os2.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <process.h> 

struct 

{ 

unsigned int Delay; 


FIGURE 4.6: A program that uses a generic //O control command to set the repeat rate of the keyboard 
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unsigned int Rate; 

} 

Parms; 


void main (int argc, char *argv[]) 

{ 

unsigned int ErrorCode; 
unsigned short Handle; 
unsigned int Action; 


if (argc != 3) 

printf ("usage? FIG4_6 delay rate\n"); 
exit (1); 

} 

Parms.Delay = atoi (argv [1]); 
if (Parms.Delay > 1000) 

printf ("delay must be 1 - 1000\n"); 
exit (1); 

} 

Parms.Rate = atoi (argv [2]); 
if (Parms.Rate < 1 || Parms.Rate > 30) 

{ 

printf ("rate must be 1 - 30\n"); 
exit (1); 

printf ("Delay = %d milliseconds\n",Parms.Delay); 
printf ("Rate = %d characters per second\n",Parms.Rate); 


/* Open the keyboard device 
ErrorCode = DosOpen 

("KBD$“, /* 

&Handle, /* 
SAction, /* 
0L, '/* 

0 , /* 
0x0001, /* 

0x0040, /* 

0L); /* 

if (ErrorCode) 

{ 

printf ("DosOpen error 
exit (1); 

> 


and save the file handle. 

Device name for keyboard. 

Variable to receive file handle. 
Variable to receive action code. 
Initial allocation size. 

File attribute: normal file. 

Open flags: open file if it exists. 
Open mode: read only and share. 

Must be 0. 


%d\n",ErrorCode); 


/* Use the file handle to pass the control command to the keyboard 
ErrorCode = DosDevIOCtl 

((char far *)0, /* 

(char far *)&Parms, /* 

0x54, /* 

0x04, /* 

Handle); /* 

if (ErrorCode) 

printf ("DosDevIOCtl error %d\n",ErrorCode); 
exit (1); 

} 




Data area. */ 
Control function parameters. */ 
Set typeamatic rate function. */ 
Function category. */ 
Handle to keyboard. */ 


} /* end main */ 


FIGURE 4.6: A program that uses a generic I/O control command to set the repeat rate of the keyboard 
(continued) 
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two basic steps required for generating I/O device control: first, calling 
DosOpen to open the device and obtain a handle, and second, issuing Dos- 
DevIOCtl to send a control command to the device that is associated with 
this handle. 

The DosOpen command takes the following parameters: 

DosOpen (FileName, Handle, ActionTaken, Size, FileAttribute, OpenFlag, 
OpenMode, Reserved); 

char far *PtrFileName; 
unsigned short far *PtrFileHandle; 
unsigned int far *PtrAction; 
unsigned long FileSize; 
unsigned int Attribute; 
unsigned int OpenFlags; 
unsigned int OpenMode; 
unsigned long Reserved; 

PtrFileName is the name of the device or file; the example program passes 
the reserved name for the keyboard device, KBO$. PtrFileHandle points 
to the variable that receives the file handle, and PtrAction points to a vari¬ 
able to receive a code for the action taken by DosOpen (1 means the file 
existed, 2 means the file was created, and 3 means the file existed and was 
truncated). FileSize indicates the file’s new size, and is given a value of 0 
since this parameter is not applicable to a character device. Attribute speci¬ 
fies the file attribute (such as read-only or hidden ); this parameter is 
assigned 0 to indicate a normal file. The parameter OpenFlags designates 
the action that is to be taken depending on whether the file exists; the value 
0x0001 is passed, which indicates that the file should be opened if it exists, 
and the function call should fail if it does not exist. The parameter Open¬ 
Mode contains a sequence of bit fields that specify the manner in which the 
file is to be opened (such as the access and sharing modes, the inheritance of 
file handles, and so on); this parameter is given a value of 0x0040, which 
indicates read-only access and allows other processes to share the device. 
Finally, the Reserved parameter must be given a value of 0. See the full doc¬ 
umentation of this function in the OS/2 Programmer's Reference. 

The example program next calls DosDevIOCtl, specifying the device 
control command that sets the repeat rate of the keyboard (category 04h, 
function 54h). DosDevIOCtl is called according to the following protocol: 


DosDevIOCtl (Data, ParmList, Function, Category, Handle); 
void far *PtrData; 
void far *PtrParms; 
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unsigned int Function; 
unsigned int Category; 
unsigned int Device; 

PtrData is a pointer to a buffer to receive any data returned by the Dos- 
DevIOCtl; the example program passes a null pointer, since no data is 
returned for the selected command. PtrParms is a pointer to the list of 
parameters. The chosen command accepts two parameters: an unsigned int 
specifying the desired repeat delay, followed by an unsigned int specifying 
the repeat rate. Function gives the function number of the desired control 
command (0x54), and Category gives the category of this command (0x04). 
Finally, the parameter Device is the device handle returned by DosOpen. 

Another important use for the DosDevIOCtl commands is to control a 
serial port; for example, you can use these commands to set the baud rate 
and other serial port parameters. Also, there are two categories of com¬ 
mands for controlling the disk as a physical device (08h and 09h). These 
commands can be used to circumvent the file system and perform low-level 
disk operations such as reading, writing, or formatting individual sectors 
(services similar to those provided under MS-DOS by the BIOS interrupt 
13h). To request these commands, you must use DosOpen to request a han¬ 
dle that refers not to a specific disk file, but rather to the entire disk as a 
physical device. To obtain such a handle, you must pass the physical drive as 
the PtrFileName parameter, and set on bit 15 of the OpenMode parame¬ 
ter; also, OpenFlags must be set to 0x0001. 


WRITING 1/0 
PRIVILEGED 
ROUTINES 


An OS/2 application is allowed to perform direct port I/O, and to enable 
or disable hardware interrupts, only if it meets a stringent set of require¬ 
ments. A code segment that is allowed to perform these operations is 
termed an I/O privileged segment. Chapter 2, in. the section on restricted 
instructions, describes the requirements for creating and using I/O privi¬ 
leged segments, and lists the specific instructions that you can execute in 
these segments. 

In general, it is preferable to communicate with devices through the stan¬ 
dard OS/2 API. Performing direct port I/O can interfere with the operation 
of the kernel and the device drivers. It also violates a basic tenet of program¬ 
ming under OS/2: you should program through the operating system, not 
around it. However, certain operations cannot be performed through the 
API, and yet do not justify installing a special device driver. For example, a 
graphics application may need to read specific I/O ports to determine 
whether a particular graphics adapter is present. The ability to use privi¬ 
leged instructions can also facilitate the rapid conversion of MS-DOS pro¬ 
grams, which often use these instructions. 
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Figures 4.7 through 4.10 provide an example of a program that uses priv¬ 
ileged instructions. This application contains a function (HGCPresent) 
that reads a port on the 6845 video controller to determine whether a Her¬ 
cules graphics adapter is installed. The main program, written in C, is listed 
in Figure 4.7. This program calls the external function HGCPresent, which 
returns 1 if a Hercules adapter is installed and 0 otherwise. Since HGCPre- 
sent performs direct port input, it must be contained in a separate assembly 
language module (the protected mode C library does not provide the inp or 
inpw instruction). The assembly language module is listed in Figure 4.8. 
The procedure HGCPresent is placed in its own code segment, _TEXT1, 
and therefore must be declared as a far function (that is, located in a sepa¬ 
rate segment) both in the C program (extern int far pascal HGCPresent 
(void)) and in the assembly language module (HGCPresent PROC FAR). 

HGCPresent determines the presence of a Hercules card by testing 
whether bit 7 of the display mode status port (3BAh) changes at least ten 
times during the execution of a loop of 8000h repetitions. On a Hercules 
card this bit goes low with each vertical retrace, whereas IBM cards do not 
use the bit (the basic routine was supplied courtesy of Hercules Computer 
Technology). The details of this routine are documented in the listing; the 
important feature for the present discussion is that it uses the IN instruction 
to read an I/O port. Therefore, the segment that contains this code must be 
granted special I/O privilege. 

To request I/O privilege for a given segment, you must write a linker def¬ 
inition file (which has the .DEF extension) and include the name of this file 


/* 

Figure 4.7 

This program demonstrates calling an assembly language function 


('HGCPresent') that is in an I/O privilege (IOPL) segment. 

The 


result of this function call -- whether or not a Hercules 

graphics 


card is present -- is printed. 

Prepare this program using the MAKE file: FIG4 10.MAK 

*/ 

#include <stdio.h> 

extern int far pascal HGCPresent (void); /* In FIG4 8.ASM. 

*/ 

void main () 

{ 

printf ("A Hercules card is %spresent.\n",HGCPresent () ? 

.... . " not .. 

); 

} /* end main */ 




FIGURE 4.7 : A C program that calls an assembler function with I/O privilege 
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} 

Figure 

00 



} 

r 

This 

assembly language 

file contains the procedure 'HGCPresent' 

f 

that 

is 

called by the 

'main' function in FIG4 7.C. The program 

r 

can be 

prepared by using the MAKE files FIG4_10.MAK. 

PUBLIC 

HGCPresent 



TEXT1 

SEGMENT 

BYTE PUBLIC 'CODE' ;This code segment is separate from 






;the code segment containing the 






;'main' C function. 

ASSUME 

CSs 

_TEXT1 



HGCPresent 

PROC 

FAR 








;** Test for HERCULES adapter. ** 

;This routine supplied courtesy of 
;Hercules Computer Technology. 


mov 


dx , 

03bah 

;Display status port. 


xor 


bl , 

bl 

;Clear counter. 


in 


air 

dx 

;Read port. 


and 


al , 

80h 

;Mask off all bits except 7. 


mov 


ah, 

al 

;Save bit 7 in AH. 


mov 


cx, 

8000h 

;Set loop counter. 

aO 1 s 






in 


al, 

dx 

;Read port again. 


and 


al, 

80h 

;Mask out bit 7. 


cmp 


al. 

ah 

;Test if bit has changed. 


je 


a02 


;Bit not yet changed. 


inc 


bl 


;Bit changed, increment counter. 


cmp 


bl. 

10 

;Want to see it change 10 times. 


jb 


a02 


;Need to see more changes. 


mov 


ax, 

1 

;Yes, it is a HGC. 


jmp 


a03 


;Go to end. 

a02 % 

loop 


aOl 


;Continue testing for changes. 


xor 


ax, 

ax 

;Hercules card is not present. 

a03 s 






ret 




;Return to C program. 

HGCPresent 

ENDP 





_TEXT1 

ENDS 





END 







FIGURE 4.8: An assembly language module that uses privileged instructions 


; Figure 4.9 

} Linker definition file for the programs in Figures 4.7 and 4.8 
NAME FIG4_7 

DESCRIPTION 'Example I/O Privileged Program' 

PROTMODE 

SEGMENTS TEXT1 CLASS 'CODE' IOPL 


FIGURE 4.9: A definition file, FIG4_9.DEF t for linking the programs in Figures 4.7 and 4.8 
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# Figure 4_10 

# This MAKE file prepares the program listed in Figures 4.7 through 4.9. 

fig4_7.obj : fig4_7.c 

cl /c /G2 /Zp /Lp fig4_7.c 

fig4_8.obj : fig4_8.asm 
masm fig4_8.asm; 

fig4_7.exe s fig4_7.obj fig4_8.obj 

link /NOI /NOD fig4_7 fig4_8, ,, doscalls.lib slibcep.lib,fig4_9.def 


FIGURE 4.10: A MAKE file for preparing the program of Figures 4.7 to 4.9 

in the command line to the linker. The definition file must contain the key¬ 
word IOPL in the description of the segment that contains the privileged 
instructions. For example, the following line grants I/O privilege to the seg¬ 
ment containing the HGCPresent function: 

SEGMENTS _TEXT1 CLASS ’CODE 1 IOPL 

This statement directs the linker to place the proper information in the 
.EXE header so that the segment _TEXT1 will run with I/O privilege (that 
is, at privilege level 2; normal applications run at level 3). Figure 4.9 lists the 
required linker definition file for the example program, and the next section 
of this chapter summarizes the general use of linker definition files. 

Figure 4.10 provides a MAKE file for preparing the example program, and 
Figure 4.11 illustrates the overall process required to develop a C program that 
calls a privileged routine located in an assembly language module. 

There are several additional important points regarding the use of I/O 
privileged segments. First, if the privileged function accepts parameters, 
there are two added requirements (conveniently, the example program did 
not require parameters): 

♦ The function must be declared in the C program using the pascal 
keyword. According to the Pascal calling convention, the called 
procedure restores the stack using the RET n instruction. This 
instruction is necessary to clean up the stack used by the privileged 
routine. Since the privileged routine runs at privilege level 2, it has 
a separate stack from that belonging to the calling program, which 
runs at level 3. The privileged routine is invoked through the call 
gate mechanism described in Chapter 2, which automatically 
copies a specified number of parameters from one stack to the 
other. 
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FIGURE 4.11: Preparation of a C program that calls a privileged routine in an assem¬ 
bler module 


♦ To tell the operating system how many parameters must be passed 
to the privileged routine (so that it can properly set up the call 
gate), you must include an EXPORTS statement that gives the 
name of the function and the number of parameters. For example, 
the following line would tell the linker that the function Privilege- 
Fimc takes four parameters: 

EXPORTS PRIVILEGEFUNC 4 

Another rule for developing privileged routines is that under the current 
version of the operating system you cannot call functions in dynamic-link 
modules from an I/O privileged segment. Note that this restriction elimi¬ 
nates the use of the OS/2 API by privileged code. 

Also, like normal applications, privileged routines are not allowed to 
intercept hardware interrupt vectors; only device drivers can contain hard¬ 
ware interrupt handlers. Therefore, device control managed from privi¬ 
leged segments must not be interrupt-driven. 

A final consideration: As noted in Chapter 2, the IOPL configuration 
command must be set to yes to permit running programs that contain privi¬ 
leged segments. See the description of this command in Chapter 1. 
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USING MODULE 

DEFINITION 

FILES 


When linking a program that is to run under OS/2 (or under Microsoft 
Windows), you can place commands in a module definition file (with the 
.DBF extension) and include the name of this file on the link command line. 
This file defines certain properties of the program or dynamic-link library 
that is being linked, such as its name, a list of any imported or exported 
functions, the sizes of its heap and stack, and the attributes of its segments. 
The name of the module definition file is an optional linker parameter, and 
it comes last on the command line (note that the OS/2 linker thus has one 
more parameter than the MS-DOS linker). The following is the command 
line syntax used by the OS/2 linker: 

LINK ObjectFiles , ExeFile , Map File, Libraries , DejFile 

All of the parameters are optional except the first (you must specify at least 
one object module). 

For most applications, module definition files are optional. If you do not 
include a definition file, all of the properties that may be defined in this file 
are given their default values. The following types of applications, however, 
require a module definition file: 

♦ Programs with I/O privileged segments (as seen in the previous 
section) 

♦ Dynamic-link library files 

♦ Windows applications 

One of the primary purposes for using a module definition file is to spec¬ 
ify the properties of the program’s segments. Under the 80286 processor 
and OS/2, each segment in memory has a fixed set of properties, such as its 
privilege level, whether it contains code or data, whether it can be shared, 
and so on. (This feature is in contrast to MS-DOS and the 8086 processor, 
under which program segments do not retain their identities once they are 
loaded into memory.) 

Commands in Module Definition Files 

A brief summary of the commands that can be placed in a module defini¬ 
tion file follows. See Figure 4.9, described in the last section, for a simple 
example. See also the appropriate OS/2 programmer’s reference manual 
for complete documentation on these commands. 

UhME This command identifies the executable file as an application pro¬ 
gram (not a dynamic-link library). You can also specify a name for the 
application and an application type (both specifications are optional). If 
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this command is used, it must come first in the file. You cannot include both 
a NAME and a LIBRARY statement; if neither statement is included, then 
the linker creates an application (in other words, the NAME command is 
the default). 

LIBRARY This command identifies the executable file as a dynamic-link 
library. You may also specify a name for the library and the type of initiali¬ 
zation performed (both specifications are optional). If this command is 
used, it must come first in the file. You cannot include both a LIBRARY 
and a NAME statement; if no LIBRARY statement is included, then the 
linker creates an application program by default (whether or not there is a 
NAME statement). 

DESCRIPTION This command is used to place a string directly into the exe¬ 
cutable file. It is useful for embedding copyright or version information. 

CODE This command specifies default attributes for all code segments 
within the application or library. The default values set by this command 
can be overridden for individual segments through the SEGMENTS com¬ 
mand. Specifically, this command can be used to determine whether a code 
segment has the following characteristics: 

♦ Is preloaded or is loaded on call 

♦ Can be read as well as executed 

♦ Has I/O privilege 

♦ Is conforming (that is, it can be called from either a normal appli¬ 
cation or an IOPL segment, and it executes at the caller’s privilege 
level) 

♦ Is shared (applies to real mode Windows only) 

♦ Is movable (applies to real mode Windows only) 

♦ Is discardable (applies to real mode Windows only) 

DATA This command specifies the default attributes for all data segments 
within the application or library. The default values set by this command 
can be overridden for individual segments through the SEGMENTS com¬ 
mand. This command can be used to specify whether a data segment has the 
following characteristics: 

♦ Is preloaded or is loaded on call 

♦ Can be written to as well as read 
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♦ Occurs only once or is copied for each instance of the program 

♦ Has I/O privilege (that is, can be accessed by I/O privileged code) 

♦ Is shared 

♦ Is movable (applies to real mode Windows only) 

♦ Is discardable (applies to real mode Windows only) 

SEGMENTS This command allows you to define attributes for one or more 
specific code or data segments. The values you set with this command over¬ 
ride the default values set by the CODE and DATA commands. You must 
provide the segment name, you can optionally include a segment class (the 
default class is ‘CODE 5 ), and you can specify any of the segment attributes 
that can be given with the CODE or DATA commands described above. 

STACKSIZI This statement specifies the size of any stack segment that has 
been defined in the program, and it overrides the size set by the application 
or by the linker /STACKSIZE option. 

EXPORTS This command serves two distinct purposes. First, it is used by 
dynamic-link library modules to list the names and attributes of all func¬ 
tions that it makes available to other programs. See Chapter 11 for more 
information on this topic. Second, the EXPORTS command can be used to 
specify the number of parameters to be passed to a function with I/O privi¬ 
lege. This use for the EXPORTS statement was described in the section on 
writing I/O privileged routines, earlier in this chapter. 

STUB This statement specifies the name of a program that is added to the 
executable file. The code from this program is executed if the user attempts 
to run a protected mode program under MS-DOS or in the compatibility 
box of OS/2. Such a program would typically print a message stating that 
the program requires the protected mode of OS/2, and then terminate. 
Note that this program must be capable of running under MS-DOS (there¬ 
fore, you cannot use OS/2 API calls). 

HEAPSIZE This command defines the size of the program's local heap. It 
affects only application programs and not dynamic-link libraries. 

PROTMODE This statement indicates that the application will run only 
in protected mode (such a program cannot be bound, as described in Chap¬ 
ter 5). 
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OLD This command affects only dynamic-link modules. A dynamic-link 
function can be identified both by a name and by a numeric ordinal value. 
An updated version of a dynamic-link library should associate the same 
ordinal value with a given function name as is associated with this name in a 
prior version. The OLD command will search a prior version of the library 
and automatically assign to each function name in the updated version the 
same ordinal value associated with this name in the prior version. (Note that 
this assignment will be performed only if the name is found in the prior ver¬ 
sion, and if the new version has not explicitly assigned an ordinal value to 
the function.) See Chapter 11 for more information on this command. 


T erminate-and-stay-resident (TSR) utilities are an important special class 
of MS-DOS programs. These utilities load themselves permanently into 
memory and allow the user to run other tasks. TSRs subsequently either 
continue running in the background (such as print spoolers), or remain dor¬ 
mant until the user presses a hotkey (for example, notepad editors). This 
section introduces the topic of converting MS-DOS TSRs to OS/2, and of 
developing OS/2 applications that perform tasks similar to those per¬ 
formed by MS-DOS TSRs. OS/2 background programs, first introduced in 
Chapter 1, are only roughly equivalent to TSRs under MS-DOS. Whether a 
utility should be developed as a background program depends upon the 
type of function it performs. 

MS-DOS TSRs that are highly interactive with the user, such as notepad 
editors and appointment calendars, are best converted to normal OS/2 pro¬ 
grams that run in a protected mode screen group. The user can activate 
these utilities at any time by switching their screen group into the fore¬ 
ground, in the same manner that the user can activate an MS-DOS TSR by 
pressing a hotkey. The operating system automatically handles the details of 
saving and restoring screen data, and of routing all keyboard and mouse 
input to the proper screen group. 

MS-DOS TSRs that are largely noninteractive, such as keyboard macro 
processors and print spoolers, are best converted to OS/2 background pro¬ 
grams. As mentioned in Chapter 1, background programs belong to a spe¬ 
cial “screen group” that cannot be brought to the foreground and that does 
not appear in the program selector list of the session manager. These pro¬ 
grams can be started directly from the configuration file with the RUN = 
command, or from the command line with the DETACH command. Run¬ 
ning a program in the background hides that program from the user and 
prevents wasting a screen group on an application that does not need to 
communicate with the console (only 12 screen groups are allowed). 
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SUMMARY OF 
SYSTEM FILES 


Note that you can also run in the background certain programs that are 
normally interactive. These programs, however, must perform console I/O 
through the standard file handles, and the standard file handles must be 
redirected to appropriate disk files. For example, the following command 
runs the OS/2 TREE utility in the background, redirecting screen output to 
a disk file: 

detach tree IF > treefile.txt 

Here are general guidelines for developing OS/2 background programs: 

♦ The program can perform console I/O only through the special 
popup routines provided by the Vio subsystem. See Chapter 9 for 
an explanation of these functions. 

♦ The program can, however, also perform I/O through the stan¬ 
dard input and output file handles, provided that these handles are 
redirected to disk files before the utility is loaded. 

♦ The program must either remain permanently installed (such as a 
print spooler), or it must terminate itself. No method is available 
to the user for terminating a background program. 

♦ If the background program needs to process the stream of charac¬ 
ters going to the printer (such as a print spooler), or coming from 
the keyboard or mouse (such as a macro utility), it must install a 
special routine known as a monitor . A monitor can read all data 
passing to or from these character devices, and can eliminate or 
add characters to the stream. The topic of developing monitors is 
discussed in Chapter 11. 


Table 4.6 summarizes the system files, mentioned in this chapter and in 
Chapter 5, that are used for developing a protected mode OS/2 application. 
These files, which are provided both by OS/2 and as part of Microsoft’s 
OS/2 development tools, present a somewhat confusing array. This chart 
serves to clarify the special uses for each file. 
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File 

•w 

Contents 

▼ 

OS2.H 

Basic C header file that includes all definitions required 
to call OS/2 API functions. You must specify the 
definitions you want included by defining appropriate 
constants before including this file. See the compiler or 
the Programmer’s Toolkit documentation for a list of 
these constants. 

OS2.INC 

OS/2 header file for assembly language programs; 
equivalent to OS2.H. 

DOSCALLS.LIB 

Import library containing dynamic-link references for 
all OS/2 function calls. If you compile with the /Lp 
option, this file is automatically searched. 

API.LIB 

Standard library containing bindings for all OS/2 

Family API functions; used for developing dual-mode 
applications. See Chapter 5. 

cLIBC/m.LIB 

Microsoft C combined library file, where c stands for 
the particular code model (S, M, C, or L),/is the type 
of floating-point code (E, 7, or A), and m is the 
processor mode (R or P). If you prepare the program 
with the CL command and the /Lr or /Lp switch, the 
appropriate file is automatically specified for the linker. 

If you link separately, you must explicitly name the 
required library. Note that these libraries generally 
replace the default C library, cLIBC/.LIB. 

DOSCALLl.DLL 

KBDCALLS.DLL 

VIOCALLS.DLL 

etc. 

Dynamic-link library files containing the code for the 
OS/2 system calls; must be in the root directory or in 
the subdirectory specified by the LIBPATH 
configuration command when running the program. 


TABLE 4.6: Files Used for OS/2 Protected Mode Applications 
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Application for 
Both Real and 
Protected Modes 

OS/2 dual-mode applications are specially prepared programs that 
can run in either protected mode or real mode. These programs, also 
known as family or bound applications, are compatible with three dis¬ 
tinct environments: an OS/2 protected mode screen group, the OS/2 
DOS compatibility box, and MS-DOS version 2.0 and later. 

Since these programs must be capable of running under MS-DOS, 
they cannot use many of the new and unique features of OS/2. The 
programs discussed in Chapter 4—simple protected mode applica¬ 
tions that have been converted from MS-DOS—are ideal candidates 
for conversion to dual-mode programs. Once you have ported an MS- 
DOS program to the protected mode of OS/2, the next logical step is 
to convert this program into a dual-mode application; the dual-mode 
option would then allow you to support both MS-DOS and OS/2 by 
maintaining a single source program and distributing a single execut¬ 
able file. If, however, you subsequently begin to enhance this applica¬ 
tion to take advantage of the advanced features of OS/2, at some 
point the dual-mode option may become impractical. The dual-mode 
format is ideally suited for simple utilities that are useful under both 
MS-DOS and OS/2. Most of the OS/2 external utilities, such as 
DISKCOPY and SORT, are dual-mode programs; these programs 
can therefore run in the real mode screen group as well as in any of the 
protected mode screen groups. 
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HOW A 
DUAL-MODE 
PROGRAM 
WORKS 


The first section in this chapter describes the mechanism that allows a 
single program to be loaded and run by either the real mode or protected 
mode command interpreters. The second section then describes the step-by- 
step procedures for developing a dual-mode application. 


At the basis of the dual-mode loading mechanism is the clever design of the 
new OS/2 .EXE file header. Before considering how dual-mode programs 
are loaded and run, you should understand the format of the new .EXE 
header, and how the information it contains is used to load standard pro¬ 
tected mode applications. 

The OS/2 protected mode loader demands much more information than 
required under MS-DOS. For example, the loader must know the attributes 
of each program segment—whether it contains code or data, whether it is to 
be preloaded or loaded on demand, its privilege level, and so on. This addi¬ 
tional information must be stored in the .EXE file header. Accordingly, the 
fields contained in the new OS/2 .EXE header are a superset of the those in 
the old MS-DOS header. In fact, the new .EXE header begins with a com¬ 
plete copy of the old header; the additional fields of the new header are 
placed beyond the old header. Figure 5.1 illustrates the format of a standard 


Protected Mode 
Pointer to Header 


Protected Mode 
Program Entry 



OLD .EXE HEADER 



OFFSET TO NEW .EXE HEADER 

STUB PROGRAM 
(Termination) 



NEW.EXE HEADER 

Entry Point 

PROTECTED MODE 

CODE AND DATA SEGMENTS 

(Termination) 


Real Mode 
Program Entry 


FIGURE 5.1: Format of a protected mode .EXE file under OS/2 
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protected mode .EXE file under OS/2, showing the header and its position 
within the program file. 

When OS/2 begins loading an .EXE file, it always sees an old MS-DOS- 
style header at the beginning of the file. There is a field within this old 
header, however, that tells OS/2 whether the program is a real mode MS- 
DOS executable file or an OS/2 protected mode (or dual-mode) program 
(specifically, if the word at offset 18h equals 40h, a value impossible for MS- 
DOS, then the file must be a protected mode program). If the OS/2 loader 
discovers that the file is an MS-DOS application, it prints an error message 
and terminates. If, however, it determines that the file is a valid protected 
mode program, it then reads the additional information in the new portion 
of the .EXE header that comes later in the file, and proceeds to load and run 
the program in a protected mode screen group. Note that the loader is able 
to locate the new portion of the header because the offset of the new header 
is contained at the end of the old header (at offset 3Ch). 

What happens if the user attempts to run a standard protected mode 
program {not a dual-mode program) under MS-DOS or the real mode screen 
group of OS/2? Since the MS-DOS loader encounters a standard MS-DOS 
.EXE header, it proceeds to load the program. Protected mode programs, 
however, are designed to prevent inadvertent execution under MS-DOS in 
one of two ways. First, the field in the old header that contains the program 
memory requirement can be set to an impossibly large value (specifically, 
the field located at offset OAh is set to the value FFFFh). When MS-DOS 
discovers this value, it prints the message Program too big to fit in memory 
and terminates. This mechanism effectively aborts an ill-fated attempt to 
load a protected mode program, but results in a confusing error message. 
OS/2, therefore, provides an alternative method. As mentioned in Chapter 
4, in the section on using module definition files, if you have specified an 
MS-DOS-compatible program with the STUB command, this stub pro¬ 
gram is inserted within the .EXE header, and the information placed in the 
old header tells the MS-DOS loader to load and ran only the stub program 
(the main application is neither loaded nor run). The stub program typically 
prints a helpful error message (such as This program requires the protected 
mode of OS/2) and immediately terminates. 

The design of the new .EXE header thus allows loading of one block of 
code under OS/2 (the main protected mode application) but another block 
of code under MS-DOS (the stub program). This mechanism forms the 
basis of the technique used to support dual-mode applications. Figure 5.2 
illustrates the structure of an OS/2 .EXE file that has been converted to the 
dual-mode format. When a standard protected mode program is trans¬ 
formed into a dual-mode program (using the BIND utility, described later 
in the chapter), two changes are made to the file. First, the stub program is 
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OLD .EXE HEADER 




OFFSET TO NEW .EXE HEADER 


Protected Mode 


STUB LOADER 


Pointer to Header 


REAL MODE VERSIONS OF ALL 
DYNAMIC-LINK FUNCTIONS 


Protected Mode 


NEW .EXE HEADER 


Program Entry 

— 

Entry Point Entry Point 



DUAL-MODE PROGRAM 
CODE AND DATA SEGMENTS 



(Termination) 


Real Mode 
Initial Entry 


Real Mode 
Entry into Main 
Application 


FIGURE 5.2: Format of a dual-mode OS/2 program under OS/2 


replaced with a stub loader. Second, real mode code for all dynamic-link 
functions called by the program is placed directly in the .EXE header fol¬ 
lowing the stub loader. These two changes will be explained in order. 

A dual-mode program is loaded in protected mode just like a standard 
protected mode application. The loader locates the new .EXE header and 
then loads and runs only the main program. The stub loader and real mode 
functions in the header are simply ignored. When the program is run under 
MS-DOS, the system loads and runs only the stub loader, in the same man¬ 
ner that it loads and runs the stub program of a standard protected mode 
application. However, rather than simply printing an error message and ter¬ 
minating, the stub loader performs the following series of actions: 


♦ It loads the dual-mode code and data into memory, segment by 
segment. 

♦ It performs the normal relocation tasks (that is, supplying segment 
values based on the actual run-time position of the program). 

♦ It resolves all references to dynamic-link functions by supplying 
the addresses of the real mode versions of these functions con¬ 
tained in the .EXE header (this step is explained in the 
following text). 
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♦ It sets up the entry conditions appropriate for the MS-DOS environ¬ 
ment (see the section on program entry conditions in Chapter 2). 

♦ It block-moves the program to its final location in memory, over¬ 
laying almost all of the stub loader code (this code is no longer 
needed, and therefore the memory it occupies can be reclaimed). 

♦ It transfers control to the main entry point of the dual-mode 
program; note from Figure 5.2 that this is the same entry point 
that receives immediate control when the program is run in pro¬ 
tected mode. 

Since MS-DOS does not support the dynamic-link mechanism, and since 
the code in the dynamic-link API libraries is suitable only for the protected 
mode, real mode versions of all dynamic-link functions must be placed 
directly within the executable file and loaded at run-time (this code is placed 
in the file by the BIND utility, discussed in the next section). The protected 
mode loader resolves all references to dynamic-link functions by loading 
the separate .DLL files and supplying the far addresses of the individual 
functions. Under MS-DOS, however, the stub loader resolves these refer¬ 
ences by supplying the addresses of the real mode versions of these func¬ 
tions that are contained immediately within the program. Note that OS/2 
supplies real mode versions for only a subset of the full API; this subset is 
known as the Family API and is discussed in the next section. Third-party 
suppliers of dynamic-link libraries can also supply real mode versions of 
their functions, which can be placed in the header of a dual-mode .EXE file, 
and which will be called if the program is loaded in real mode. 

Since many of the OS/2 API functions manage advanced features of 
OS/2, such as multitasking and interprocess communication, it would be 
difficult or impossible to supply real mode versions of these functions for 
dual-mode programs. These functions are therefore not part of the Family 
API. The real mode versions of Family API functions are implemented in 
several ways. First, many of the Dos routines are closely equivalent to stan¬ 
dard MS-DOS services; in this case the real mode version of the function 
need only load the parameters it has been passed into machine registers and 
issue interrupt 21h. Other API functions can be similarly implemented by 
invoking an appropriate BIOS interrupt. However, the real mode versions 
of most of the subsystem calls (Vio and Kbd) contain complete low-level 
routines that do not rely upon system services. These routines supply their 
own low-level code in order to provide a level of performance equivalent to 
the protected mode dynamic-link versions. For example, the real mode Vio 
routines use direct access to video memory, which provides performance 
much greater than that achieved through the BIOS video services. 
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The real mode function versions that simply load registers and execute 
an appropriate DOS or BIOS software interrupt are known as bindings . 
Note that the binding mechanism is a less direct interface to the operating- 
system services than that provided by OS/2 dynamic-link functions. Figure 
5.3 illustrates the difference between protected mode dynamic-link function 
calls and calls to real mode bindings. 


PROTECTED MODE REAL MODE 



FIGURE 5.3: A comparison of the protected mode and real mode interfaces to the 
operating-system services 

The Performance of Dual-Mode Applications 

Developing a dual-mode application is an attractive alternative to writing 
separate program versions for both protected and real modes. The dual¬ 
mode mechanism, however, exacts performance costs in four areas: 

❖ Size on disk 
$ Size in RAM 

$ Loading speed 

♦ Execution speed 

Size OP Disk Since converting a protected-mode program to the dual-mode 
format causes real mode library functions to be inserted directly into the 
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.EXE file, the resulting file is larger than the original protected mode pro¬ 
gram. (Remember that the dynamic-link functions called by a protected 
mode program are stored in a separate .DLL file.) The size increase ranges 
from approximately 5 to 30 kilobytes. A dual-mode program may also be 
slightly larger than an equivalent real mode program, since the binding 
mechanism generally requires more code than direct interrupt invocation. 

Size In RAM If the dual-mode program is loaded under protected mode it 
occupies no more memory than a protected mode program, since neither 
the stub loader nor the real mode functions are loaded in protected mode. 
If the program is loaded under real mode, its size in memory is slightly 
larger than an equivalent real mode program for the same reason men¬ 
tioned in the last paragraph. 

Loading Spesd If the dual-mode program is loaded in protected mode, the 
loading speed is the same as that for a protected mode application, since 
the loading procedures are identical. Under real mode, loading speed is 
slower than for an equivalent real mode program, since the loading is per¬ 
formed in two distinct steps (first the stub loader is loaded, and then the 
main application); an entire real mode program can be loaded in a single 
disk operation. 

Execution Speed The speed of a dual-mode program running in protected 
mode is the same as the speed of the standard protected mode version of the 
program. In real mode, the program runs slightly slower than an equivalent 
real mode application because system calls are routed through a binding 
routine, which is slower than the direct invocation of interrupts. (This state¬ 
ment applies primarily to assembly language programs; most high-level lan¬ 
guages do not allow direct invocation of interrupts, but rather use calls to 
functions similar to the bindings of dual-mode programs. For example, 
Microsoft C programs must call a function such as int86 to generate a soft¬ 
ware interrupt.) 


HOWTO 
DEVELOP A 
DUAL-MODE 
PROGRAM 


A dual-mode program is developed through the following three basic steps: 

1. Write the program so that it can run under either real mode or 
protected mode. 

2. Compile and link the program as a protected mode application. 

3. Convert the program to the dual-mode format using the BIND 
utility. 
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Note that to develop a dual-mode program, you must begin by developing a 
protected mode program; only the third step—conversion with the BIND 
utility—is entirely new. However, not all protected mode applications can 
be converted to the dual-mode format; you must perform the first two 
development steps following a special set of guidelines, which are discussed 
in this section. Figure 5.4 lists a brief C program designed to be converted to 
the dual-mode format, and Figure 5.5 provides a MAKE file to generate the 
dual-mode executable file. This program can run under MS-DOS, in the 
compatibility box of OS/2, and in an OS/2 protected mode screen group; it 
simply prints a message indicating whether the current machine mode is real 
or protected. 


/* 

Figure 5.4 

This program exemplifies a simple dual-mode application. 

Prepare the dual-mode executable file using the MAKE files FIG5 5.MAK 

*/ 

#define INCL_DOSMISC 
#include <os2.h> 

#include <stdio.h> 

#include <conio.h> 

void main () 

{ 

unsigned char ProtectedMode; 

DosGetMachineMode (SProtectedMode); /* You could also use the C */ 

/* variable '_osmode'. */ 

printf ("The current machine mode is "); 
if (ProtectedMode) 

printf ("PROTECTED\n"); 

else 

printf ("REAL\n"); 

> /* end main */ 


FIGURE 5.4: A short C program designed to run under either real or protected mode 


# Figure 5.5 

# This MAKE file compiles and links the program of Figure 5.4, and 

# converts the executable file to the dual-mode format. 

fig5_4.obj i fig5_4.c 

cl /c /GO /Zp /Lp fig5_4.c 

fig5_4.exe % fig5_4.obj 

link /NOI /NOD fig5_4.obj,,,doscalls.lib slibcep.lib; 
bind fig5_4.exe \sdk\lib\doscalls.lib \sdk\lib\api.lib 


FIGURE 5.5: A MAKE file to generate a dual-mode executable file from the program of Figure 5.4 
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Figure 5.6 illustrates the basic development process for a dual-mode pro¬ 
gram that incorporates an assembly language module. Note that this figure 
is an extension of Figure 4.11, which shows the basic process for generating 
a standard protected mode application. 



FIGURE 5.6: The basic process for developing a dual-mode application 


Writing the Program 

The fundamental guideline for writing a dual-mode program is to follow 
the rules for developing a real mode application (some of which were dis¬ 
cussed in Chapter 3) plus the stronger set of rules for developing a protected 
mode application (discussed in Chapters 2 and 4), since the program must 
be capable of running in either environment. This section discusses several 
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specific guidelines that are of immediate importance when writing a dual¬ 
mode application. 

The first guideline is that if your program is running in real mode, you 
must not call dynamic-link functions that do not have equivalent real mode 
functions bound into the executable file. As explained in the previous sec¬ 
tion, when a program is loaded under real mode, calls to OS/2 dynamic- 
link functions are routed to equivalent real mode functions that are read 
into memory from the .EXE file. Equivalent real mode functions, however, 
are not available for all dynamic-link functions. OS/2 supplies real mode 
equivalents only for the Family API functions, which form a proper subset 
of the full API; third-party suppliers of dynamic-link libraries may or may 
not supply real mode versions for all of the functions in their libraries. 

There are two basic ways to prevent calling nonsupported dynamic-link 
functions when the program is running in real mode: simply eliminate all 
calls to these functions from your program, or test the machine mode at 
run-time and call these functions only if the machine is in protected mode. 

If you choose to eliminate all dynamic-link function calls that are not 
supplied in real mode versions, then you must restrict your operating- 
system calls to the Family API functions. These functions are clearly 
marked in the list of the API given in the endpapers. Family API functions 
are similar to those provided for MS-DOS programs by the interrupt 21 h 
interface and by the ROM BIOS. The Family API excludes functions that 
manage advanced features of OS/2 such as multitasking and interprocess 
communication. Note also that certain functions that are members of the 
Family API operate differently in real and protected modes. These func¬ 
tions are also marked in the endpapers, and you must be careful not to use 
any features that are dependent upon a specific mode. An example is the 
Family API function DosExecPgm. This function, which executes a child 
process, can be used in both real and protected modes; if it is called in real 
mode, however, you are not permitted to execute the child process asyn¬ 
chronously. (Asynchronous execution of a child process causes the parent 
and child processes to run concurrently, a feature that requires a multitask¬ 
ing operating system; this topic is discussed in Chapter 6.) 

The second method to prevent calling dynamic-link functions that are 
supported only in protected mode is to first test the current machine mode, 
and then call these functions only if the program is running under protected 
mode. To test the machine mode, you can call the API function DosGet- 
MachineMode; this function returns 1 if the current mode is protected, and 
0 if the machine is in real mode. You can use this function to branch to the 
appropriate section of code, as in the following example: 

unsigned char ProtectedMode; 
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DosGetMachineMode (& Protected Mode); 
if (ProtectedMode) 

/* Protected-mode-specific code, including */ 

/* non-Family API calls. */ 

else 

/* Real-mode-specific code; ail API calls */ 

/* must be in Family subset. */ 

Figure 5.7 illustrates the use of DosGetMachineMode to branch to the 
appropriate alternate routine. Interfacing with a mouse is a good example 
of a task that requires separate real mode and protected mode routines. The 
OS/2 mouse functions (the Mou calls) are not part of the Family API sub¬ 
set, and are therefore not available to a dual-mode program running under 
real mode. However, in real mode the same services can be obtained 
through interrupt 33h calls to the mouse driver. 

The DosGetMachineMode function is useful not only for testing 
whether you can use non-Family API calls, but also for determining 
whether you can use any feature peculiar to either real or protected mode. 
For example, if the program is in real mode, you can intercept keystrokes by 
providing a keyboard hardware interrupt handler (interrupt 09h); if the 
program is in protected mode, however, you must install a keyboard moni¬ 
tor (see Chapter 11 for details). Also, you can call DosGetMachineMode to 



FIGURE 5.7: Using DosGetMachineMode to branch to alternate routines 




determine whether you can use a mode-specific feature of a F amil y API 
call, such as the asynchronous option of DosExecPgm mentioned above. 

Note that if you are writing long protected mode routines, which employ 
advanced features of OS/2, your program is most likely outgrowing the 
dual-mode format. Remember that this format is designed primarily for 
simple, MS-DOS-style programs. Note also that you cannot use the API 
function DosGetVersion to determine the current mode, since this function 
returns the same value when called either from the real mode screen group 
or from a protected mode session. A final point: When calling non-Family 
API functions from a dual-mode program, you must declare the names of 
these functions when using the BIND utility (with the - n option, discussed 
in the section on using BIND, later in the chapter). 

The following are two additional guidelines for writing dual-mode 
programs: 

♦ Do not use machine instructions specific to the 80286 or 80386 
processors. Unlike protected mode programs, dual-mode pro¬ 
grams should be able to run on any MS-DOS machine, many of 
which employ the 8086/88 processors. See the next section for 
information on the appropriate compiler and assembler switches 
for generating code compatible with the 8086/88. 

♦ Do not exceed the 640-kilobyte memory limit, since real mode 
programs do not have the benefit of the large virtual memory 
space provided in protected mode. 

Compiling and Linking the Program 

Once you have completed the source program, following the rules described 
in the last section, the next step is to use the compiler and linker to generate 
a protected mode application. The procedure for compiling the program 
is the same as that described in Chapter 4, except that you should not 
allow the compiler to generate instructions specific to the 80286/80386 
processors. Therefore, you should replace the /G2 command line option, 
which allows the generation of 80286 instructions, with the /GO option, which 
forces the compiler to produce only 8086/88 instructions (this option is the 
default, and therefore does not have to be explicitly included in the com¬ 
mand line). For a program consisting of a single source file, you can use the 
CL driver as follows: 

cl /GO /Zp /Lp prog.c 

For a program consisting of more that one source file, you can use the 
MAKE utility as described in Chapter 4. See the example MAKE file listed 
in Figure 5.5. 
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In an assembly language module written under Microsoft MASM, you 
should not use any of the directives that allow assembly of instructions for 
processors later than the 8088, such as .286, .287, and .386. The default 
mode is to allow assembly of instructions only for the 8086/88 and 8087 
processors. 

Converting the Executable File 
to the Dual-Mode Format 

The final step for preparing a dual-mode application is to process the pro¬ 
tected mode .EXE file with the BIND utility, producing a dual-mode .EXE 
file. Note that before the protected mode file is converted with BIND, it is a 
fully functional program that can run only in protected mode. You might 
therefore want to debug this program in protected mode before generating 
the dual-mode version and testing it in real mode. 

The BIND utility performs the following actions on the .EXE file: 

♦ It places a stub loader within the .EXE file header. 

♦ It places real mode versions of all supported dynamic-link func¬ 
tions within the .EXE file. 

♦ It sets up the file size and entry point fields of the header so that 
if the program is run in real mode, the operating system will load 
only the stub loader program and will pass the stub loader initial 
control. 

The syntax of the BIND command is as follows: 

BIND InFile [ImpLibs] [LinkLibs] [-o OutFile] [~n [@ NameFile]] 

[-m [MapFile]] 

The parameters have the following meanings: 

InFile The name of the protected mode application you want to 

convert to the dual-mode format. If you leave off the file 
extension, .EXE is assumed. 

ImpLibs The name of one or more import libraries. Some link libraries 
(such as API.LIB) require you to specify the original import 
library used to link the program (for API.LIB, you must specify 
DOSCALLS.LIB). An import library tells BIND the actual 
function name that is associated with each dynamic-link record 
in the .EXE header. Note that you must specify the full path 
name. 
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LinkLibs The name of one or more standard object-code link libraries 
that contain real mode versions of all supported dynamic-link 
functions called by your program. The real mode versions of the 
Family API system functions are included in the library 
API.LIB. If you do not specify a file, BIND will automatically 
look for API.LIB in the directory specified by the LIB 
environment variable and will search this library to resolve 
dynamic-link references. Note, however, that if you specify a 
file, you must always supply the full path name . 

OutFile The name of the resulting dual-mode application. By default, 
this file is given the same name as InFile. 

Name File Following the - n option, you may list the names of functions 

that do not have real mode versions in LinkLibs , such as the 
non-Family API services. Also, rather than listing the function 
names on the command line, you can place them in a text file, 
one per line, and specify the file name following the @ sign. If 
any of the functions given with this option is called in real 
mode, OS/2 passes control to the function BadDynLink, which 
prints an error message and aborts the program. If your 
program contains a call to a dynamic-link function that does not 
have a real mode version in a link library, and if you do not 
specify the name of this function with the - n option, BIND will 
generate an “unresolved reference” error message and will fail 
to convert the program. This option is therefore vital for 
programs that contain non-Family API calls. 

MapFile The - m option causes BIND to generate a link map file that 

describes the program as it is loaded under MS-DOS. MapFile is 
the name of this file; if you do not supply a name, the map 
information is written to standard output. 

Note that there must be a space after the - o, - n, and - m flags, and 
before the first accompanying name. As an example, the following com¬ 
mand converts the protected mode program PROG.EXE to a dual-mode 
program having the same name: 

bind prog.exe \lib\doscalls.lib \lib\api.lib 
- n DosGetlnfoSeg 

The program in this example, PROG.EXE, can call only dynamic-link 
functions belonging to the Family API, plus the non-Family API function 
DosGetlnfoSeg. If the code mistakenly calls DosGetlnfoSeg in real mode, 
control passes to the function BadDynLink, which terminates the program 
after printing the following error message: 

The Application Program Interface (API) entered will only work in 
Microsoft Operating System/2 mode. 
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Note that the example command assumes that the API import library, 
DOSCALLS.LIB, and the API real mode object library, API.LIB, are both 
contained in the \LIB directory of the current disk. The specification 
\LIB\API.LIB could have been omitted from the command line. See also 
the MAKE file of Figure 5.5. 

Note also that the CL driver supplied with version 5.1 of the Microsoft C 
compiler will automatically issue the BIND command and produce a bound 
executable file if you use the /Fb command. See the compiler documenta¬ 
tion for details. 

Since API.LIB is a standard MS-DOS library file, you can also call OS/2 
Family API functions from MS-DOS programs. Simply include the appro¬ 
priate declarations, compile the program, and link with the library file 
API.LIB. The Kbd and Vio functions, which are especially useful for an 
MS-DOS program, would provide your MS-DOS and OS/2 applications 
with a common console interface. 

Developers of third-party dynamic-link libraries can also supply libraries 
containing real mode versions of their functions. Such link libraries are analo¬ 
gous to API.LIB, and would allow the programmer to develop dual-mode ver¬ 
sions of programs that call these functions. The topic of developing 
dynamic-link libraries is discussed in Chapter 10. 
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Using 

Multitasking 

The last three chapters explored the basic procedures for programming 
under OS/2 by explaining how to write simple, MS-DOS-style applica¬ 
tions that can run in the OS/2 real mode, in the protected mode, or in 
either of these modes. This chapter begins the treatment of the advanced 
features of OS/2 by introducing multitasking—how it is implemented 
and how you can take advantage of it in your programs. 

Chapters 1 and 2 described the three levels of OS/2 multitasking: 
threads, processes, and screen groups. This chapter deals individually 
with each of these levels—defining the basic concepts, discussing how 
to use the relevant OS/2 API functions, and providing example pro¬ 
grams. The emphasis is placed upon threads and processes, since these 
levels are of greatest practical importance to the application program¬ 
mer. Note that the discussions of the OS/2 API functions in this and 
the remaining chapters serve to complement rather than duplicate the 
OS/2 technical documentation; if you are writing an application, you 
should also refer to an OS/2 programmer’s reference manual for the 
exact function-calling protocols. Chapter 7 continues the discussion 
of multiple OS/2 processes with the closely related topic of inter¬ 
process communication. 
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MULTITASKING As mentioned in Chapter 1, a given OS/2 process consists of one or more 

OF THREADS threads . A thread under OS/2 represents the passage of the processor 

through a sequence of machine instructions. A thread is the basic dispatch- 
able entity; the OS/2 scheduler divides time slices among the active threads 
in the system according to their relative priorities. The scheduler has no 
knowledge of processes; it dispatches threads without regard to the various 
processes that own them. 

This section first discusses some of the general properties of threads. 
Next—since threads are the basic dispatchable entity under OS/2—it 
describes how the system assigns priorities to threads and divides processor 
time among them. Finally, you will learn how to use the OS/2 API services 
for creating and managing multiple threads in an application. 

When your program begins running, it consists of a single thread of exe¬ 
cution (as do almost all MS-DOS applications). Under OS/2, however, any 
thread can start a new thread by calling the API function 
DosCreateThread. This function returns control immediately, and the new 
thread begins running concurrently with all other threads in the system. 
Threads execute independently of one another; they are said to be asyn¬ 
chronous, meaning that they run simultaneously but without timing rela¬ 
tionships. (That is, when a thread is executing a particular instruction, it 
cannot be predicted what instruction any other thread is currently execut¬ 
ing.) Also, a given thread bears no special relationship to the thread that 
started it (unlike processes, which form parent-child associations to be 
described later). In addition to starting new threads, you can also alter the 
priority of threads, suspend threads temporarily, or terminate the current 
thread or all threads belonging to the process. 

When you initiate a new thread, you must specify the address of the 
entry point; in a high-level language, you generally pass the address of a 
function that is to be executed by the thread. Therefore, from the viewpoint 
of a high-level language, a thread can be defined as the concurrent execu¬ 
tion of a subroutine. 

Note that threads belong to the process in which they are started; they 
are not visible to other processes (outside of the owning process, they are 
known only to the system scheduler). All the threads belonging to a process 
share the resources of that process, such as memory segments and file han¬ 
dles. Associated with each thread, however, are the following items of pri¬ 
vate information: 

♦ A thread ID 

♦ A thread priority 

♦ The current thread state: ready, running, or blocked 
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♦ The length of the thread's time slice 

♦ The CPU register and flag contents when the thread was last sus¬ 
pended (that is, the machine state associated with the thread) 

♦ The state of the numeric coprocessor (80287/387) when the thread 
was last suspended 

♦ The current default disk drive and directory belonging to the parent 

You can set the maximum allowable number of threads through the 
THREADS = n configuration command, where n is the desired number of 
threads and is a value between 16 and 255. Note that this value represents 
the maximum number of threads in the entire system, not the number 
allowed for a specific process. 

Thread Priorities and Scheduling 

Each thread managed by the OS/2 scheduler is assigned a priority The basic 
scheduling algorithm is simple: at any given time, the system executes the 
highest-priority thread that is ready to run; if several threads share the highest 
priority, they are run in a round-robin fashion. Although this fundamental 
algorithm is followed without exception, the overall scheduling strategy used by 
OS/2 is more complex; to maximize system responsiveness and increase 
throughput, the scheduler can dynamically adjust the priorities of individual 
threads according to criteria that will be discussed in this section. 

At a given time, a thread is in one of the following three states: 

♦ Running : The thread is currently receiving CPU machine cycles. 

♦ Ready : The thread is not currently running, but is eligible to run; it 
may be allowed to run when the scheduler becomes active, pro¬ 
vided it has a sufficient priority level. 

♦ Blocked : The thread is not currently eligible to run; typically, it is 
either “sleeping” or is waiting for some system resource to become 
available. 

A thread can remain blocked —and therefore not consume any CPU clock 
cycles—when it is waiting for a system resource, which is an important fea¬ 
ture for maximizing the efficiency of a multitasking system. The topic of 
when and how threads block is discussed in the next chapter. 

The scheduling of threads under OS/2 is also preemptive , meaning that 
when a thread is no longer qualified to run it is forcibly suspended, or pre¬ 
empted, by the system. In fact, a thread can be suspended between any two 
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machine instructions (this possibility requires that you take special pre¬ 
cautions—discussed later in the chapter—to preserve the integrity of shared 
data). Specifically, a thread is preempted when either of the following 
events occurs: 

♦ Another thread, which has a higher priority, becomes ready to run. 
(This can occur, for example, if a system call or hardware interrupt 
routine frees some resource for which the higher-priority thread 
has been waiting.) 

♦ The thread’s time slice expires. The system receives control with 
each clock-tick interrupt, which gives the scheduler frequent 
opportunities to check the status of all threads. If the time slice of 
the current thread is exhausted and if another thread of equal (or 
higher) priority is ready to run, the current thread is preempted; 
otherwise, it is allowed to continue running. 

Note that the minimum length of a time slice can be specified through the 
first number given with the TIMESLICE = configuration command (see 
Chapter 1). Each time a thread uses its complete time slice without being 
preempted, however, its time slice is increased by one clock tick (32 millisec¬ 
onds) until reaching the maximum time-slice value given by the second 
number specified in the TIMESLICE = command. 

If the scheduler algorithm runs only the highest-priority eligible thread, 
how can lower-priority threads ever receive processor cycles? The opportu¬ 
nity for lower-priority threads to run comes when higher-priority threads 
block. In a typical system, a high-priority thread may block quite fre¬ 
quently, either through the action of another thread in the same process, or 
when the thread voluntarily waits for a system resource. For example, inter¬ 
active programs (which run at the highest priority level when they are in the 
foreground) usually spend a large amount of time waiting for keystrokes. 
When reading the keyboard using the OS/2 Kbd functions, the calling 
thread becomes blocked while waiting for a keystroke, rather than wasting 
processing cycles in a polling loop. (Also, as will be described shortly, a 
thread in the regular priority class that has been waiting a sufficient time 
may receive a temporary boost in priority to allow it to run.) 

A thread under OS/2 belongs to one of the following three priority 
classes : 

♦ Time-critical class 

♦ Regular class (also called the general or normal class) 

♦ Idle-time (or low-priority) class 
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Note that threads in the time-critical class have the highest priority, and 
threads in the idle-time class have the lowest priority Note also that threads 
within a given priority class are further subdivided into 32 distinct priority 
levels , numbered from 0 to 31. Thus, for example, a thread belonging to the 
regular class at level 0 has a slightly greater priority than a thread in the idle¬ 
time class at level 31. The three priority classes are illustrated in Figure 6.1. 
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FIGURE 6.1: The three OS/2 priority classes 
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When a thread is created, it inherits the current priority of the thread that 
created it. You can also use the DosSetPrty function to assign a thread a spe¬ 
cific priority class and a priority level within this class. (Note that DosSet¬ 
Prty allows you to specify the priority class directly; the priority level, 
however, can be given only as a change from the current level, and is a value 
ranging from - 31 to +31. You can first obtain the current priority level by 
calling BosGetPrty or DosGetlnfoSeg.) DosSetPrty also allows you to set 
the priority for one or more entire processes (explained later in the chapter). 
Under version 1.0 of OS/2, however, setting the priority of a process affects 
only those threads that have not had their priority specifically altered from 
within the process through DosSetPrty. 

The time-critical class is appropriate for threads that must receive 
prompt attention from the CPU. One example is the thread of a communi¬ 
cations program that processes incoming characters. Such a thread could 
lose characters if it were placed in the regular priority class. Another 
example is a print spooler; although this type of program does not seem like 
a typical time-critical application, it uses so little CPU time that you might 
as well allow it to quickly grab a short spurt of processor time whenever 
required to keep the printer continuously busy. A final example is a thread 
that serves as a monitor . A monitor intercepts characters coming to or from 
a character device, and it must process these characters rapidly to prevent 
delaying I/O. (See Chapter 11.) 
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Assigning too many threads to the time-critical class can markedly 
degrade the performance of interactive foreground applications (which 
normally run in the regular class). You should therefore assign time-critical 
priority only to those threads that decidedly require high priority; all other 
threads should be left in the regular class. OS/2 is designed to favor the 
responsiveness of the foreground application over the general system 
throughput; you should be careful not to defeat this design feature by 
unnecessarily assigning threads to the time-critical priority class. 

Threads in the idle-time class have the lowest priority. These threads 
receive processor time only during the relatively rare instants when all of the 
threads in the two higher classes are blocked. This category is thus not prac¬ 
tical for most types of applications. 

The majority of application threads run within the regular priority class, 
which offers an intermediate level of priority. Like the other two priority 
classes, threads within this class are assigned one of 32 priority levels. However, 
unlike the other two classes, the OS/2 scheduler can dynamically adjust the pri¬ 
orities of the threads within the regular class in one of three ways. 

First, thread priorities are dynamically adjusted so that the priorities of 
all threads belonging to foreground processes are higher than the priorities 
of threads in background processes. (Remember that a process comes into 
the foreground when the user switches into the screen group that contains 
this process.) This form of dynamic adjustment is in accord with the OS/2 
goal of emphasizing the responsiveness of the user interface rather than 
overall system throughput. Note that the next two types of dynamic priority 
adjustment cannot alter this basic relationship; background threads can 
never compete for processor time with foreground threads. 

Second, OS/2 can dynamically adjust the priority of a thread to prevent 
it from becoming totally starved of CPU time. If a thread in the regular 
class has been denied processor time for more than the maximum allowable 
waiting time, then its priority is temporarily increased for a single time slice 
to allow the thread to run. Once the thread has run for a time slice, its prior¬ 
ity reverts to its former value. Note that the maximum allowable waiting 
time can be specified through the MAXWAIT = configuration command; 
the default value is 3 seconds (see the description of this command in Chap¬ 
ter 1). 

Third, threads that frequently block—typically while performing I/O 
operations—are given a small relative increase in priority. Since these 
threads spend most of their time waiting for I/O operations to complete, 
they use little processor time. By allowing them rapid access to the CPU 
when necessary, they can keep I/O operations going continuously, while 
stealing relatively few machine cycles from CPU-bound processes. Thus, 
overall system throughput is enhanced. 
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Note that the last two forms of dynamic priority adjustment—yielding 
processor time to deprived threads and increasing the priority of frequently 
blocking processes—can be defeated by specifying the PRIORITY = AB¬ 
SOLUTE configuration option, which forces the scheduler to use the stati¬ 
cally defined priority levels. 

Using Multiple Threads 

The uses for multiple execution threads are limited only by the imaginations 
of the programmers who will begin to develop increasingly sophisticated 
applications for the microcomputer environment. The following are three 
examples of ways multiple threads can be used within typical applications. 

First, multiple threads can be used to increase the responsiveness of the 
user interface and to maximize system throughput by accepting commands 
from the user at the same time as previously entered commands are being 
executed. One thread can be dedicated to receiving user input, and one or 
more threads can be used to execute the commands that have already been 
received. Figure 6.2 compares a single-thread program with a multiple- 
thread program. The increase in responsiveness and throughput is espe¬ 
cially significant if the commands take a relatively long time to execute, 
such as saving a file on a disk, recalculating a spreadsheet, or redrawing a 
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FIGURE 6.2: A single-thread program vs. a multiple-thread program 
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complex graphics screen. In a multiple-thread program, the user can begin 
entering subsequent commands while previously entered commands are 
being completed. 

Second, a separate dedicated thread can be used to perform a subsidiary, 
asynchronous task required by the program. For example, an application 
that contains a long, noninteractive procedure (such as a sort operation or 
an involved graphics display) may need to simultaneously monitor the key¬ 
board so that the user can interrupt the procedure and perhaps return to a 
main menu. A single-thread application would have to intersperse explicit 
calls to a keyboard routine throughout the main body of code. A multiple- 
thread application, however, can dedicate a separate thread to monitoring 
the keyboard, thereby providing a faster response to entered keystrokes and 
simplifying the code. 

Finally, using multiple threads can greatly simplify coding a complex 
application that can be divided into a collection of logically distinct, simul¬ 
taneous tasks. The example cited in Chapter 2 (in the section on Multitask¬ 
ing and Interprocess Communication) is a communications program that 
must simultaneously read characters from the serial port, display characters 
on the screen, read characters from the keyboard, and send characters to 
the serial port. Each of these discrete functions is an ideal candidate for a 
separate thread. 

Table 6.1 lists in alphabetical order the OS/2 API services that can be 
used to create and manage multiple threads. Note that this table gives only 
the uses for these functions that apply specifically to threads; some of the 
functions deal also with other levels of the system (for example, DosGetln- 
foSeg returns system, process, and thread information; only the informa¬ 
tion it supplies regarding the current thread is mentioned in the table). 

When you create a new thread with DosCreateThread, you must specify 
not only the entry point of the code that the thread is to execute, but also the 
address of the top of stack to be used by the thread. Your program is 
responsible for allocating space for this stack; it is not automatically pro¬ 
vided by the system. Microsoft recommends providing a stack for each 
thread that contains at least 2 kilobytes in addition to the requirements of 
the thread itself. This additional stack memory is required for any dynamic- 
link routines that are called from the thread (dynamic-link routines may 
require a significant amount of space on the stack). For example, the fol¬ 
lowing C code declares a function to be executed by a separate thread, 
reserves a 3-kilobyte stack, and creates the new thread: 

void far ThreadOl Function (void); 
unsigned int ThreadOl ID; 
unsigned char ThreadOl Stack [3072]; 
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Function 

Purpose 

DosCreateThread 

Starts a new thread within the current process. You 
pass the addresses of the thread’s entry point and 
stack; the function returns the ID of the new thread. 

DosEnterCritSec 

Temporarily suspends all threads in a process except 
the current one. This function is used to serialize 
execution of a critical section of code. 

DosExit 

Terminates the current thread . 

DosExitCritSec 

Resumes all threads previously suspended by 
DosEnterCritSec. 

DosGetlnfoSeg 

Returns the ID and priority of the current thread, 
and indicates whether the current thread is running in 
a foreground process. It also supplies the current 
parameters used by the scheduler, such as the 
minimum and maximum time slices. See Figure 2.8 
for an example of using this function. 

DosGetPid 

Obtains the ID of the current thread. 

DosGetPrty 

Gets the priority class and priority level of the current 
thread, or of a thread that is specified by its ID. 

DosResumeThread 

Restarts the execution of a thread previously 
suspended by calling DosSuspendThread. You need 
to pass the ID of the thread. 

DosSetPrty 

Sets the priority class and priority level of a thread 
within the current process. You must pass the thread 

ID, the desired priority class, and the amount by 
which you would like the priority level adjusted. 

DosSuspendThread 

Temporarily suspends the execution of a thread. You 
must pass this function the ID of the thread to 
suspend. 


TABLE 6.1: OS/2 Functions for Managing Multiple Threads 
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DosCreateThread (ThreadOl Function,&Thread01 ID,ThreadOlStack 
+ sizeof (ThreadOl Stack)); 

The function DosCreateThread has the following C prototype: 

unsigned int pascal far DosCreateThread 
(void (far *)PtrFunction(void), 
unsigned int far *PtrThread, 
unsigned char far *PtrThreadStack); 

Note that if you include the header file containing this declaration (first 
define the constant INCL_DOSPROCESS and then include OS2.H), the 
compiler will automatically convert the addresses of the three local vari¬ 
ables that are passed as parameters to the appropriate far addresses. Also, 
you must use the /F parameter with the CL command to specify a stack 
large enough to accommodate the 3-kilobyte thread stack plus the other 
stack needs of the program (guidelines for writing C programs with multi¬ 
ple threads are discussed later in the chapter). 

A thread may terminate itself either by issuing a far return (which trans¬ 
fers control back to the dispatcher), or by explicitly issuing a DosExit call, 
as follows: 

DosExit (0,0); 

The first parameter tells OS/2 to terminate only the current thread, and the 
second parameter is a result code that applies only when DosExit is used to 
terminate a process (described later in the chapter). Note that there is no 
function that allows one thread to terminate another thread. 

Once you have created a thread, you may can adjust its priority, if neces¬ 
sary, using DosSetPrty (remember that a new thread inherits the priority of 
the thread that created it). You can obtain the priority of the current thread 
by calling either DosGetPrty or DosGetlnfoSeg. 

Since the threads belonging to a process freely share the resources of that 
process (such as data segments and disk files), and since threads run asyn¬ 
chronously, you must make sure that only one thread can access a shared 
resource at a given time. For example, a thread that is updating the fields of 
a data structure in memory can be preempted at any time; if another thread 
then accesses these same fields, it may obtain partially updated—and there¬ 
fore invalid—data. Note that it is even possible for the same body of code 
(such as a C function) to be executed simultaneously by more than one 
thread, further increasing the likelihood of the simultaneous access of 
shared resources. Such code must be reentrant , meaning that it can safely be 
preempted and—while suspended—be reentered by another thread. 

There are several tactics for preventing multiple threads from simultane¬ 
ously accessing the same resource. First, you can put data variables that do 



Using Multitasking 


not need to be shared within the stack. A new thread is always assigned a 
private stack; therefore, even if several threads execute the same function, 
each thread has a separate copy of these local variables and no conflicts 
are possible. 

Second, for data or other resources that must be shared, you need to 
make sure that only one thread can access the resource at a given time. An 
area of code that uses a common resource, which cannot safely be shared by 
more than one thread at a time, is known as a critical section . You must seri¬ 
alize the execution of critical sections, meaning that you must allow only 
one thread at a time to pass through any critical section that accesses a given 
shared resource. 

The OS/2 API provides a wealth of methods for protecting critical sections 
of code. If you know exactly which threads access the shared resource, and you 
know the IDs of these threads, you can use the functions DosSuspendThread 
and DosResumeThread. Before each location in the program that accesses the 
resource, you should call DosSuspendThread to suspend the execution of all 
other threads that access the same resource; note that you must make a separate 
call for each thread. When the program has finished using the resource, you 
should immediately call DosResumeThread for each suspended thread to allow 
the suspended threads to resume execution. 

The functions DosEnterCritSec and DosExitCritSec provide another 
method for serializing critical sections of code. DosEnterCritSec suspends 
all threads within the process except the current thread, and DosExit¬ 
CritSec causes these threads to resume. If many threads access a common 
resource, or if you are uncertain exactly which threads are involved, these 
functions are more convenient and are safer than DosSuspendThread and 
DosResumeThread. 

There are two important limitations, however, to using DosSuspend¬ 
Thread and DosEnterCritSec (and the corresponding functions that resume 
execution). First, these services operate only upon threads that belong to the 
current process; resources, however, can be shared among several pro¬ 
cesses. Second, these functions create an overkill situation; they arbitrarily 
suspend a process whether or not the process is about to enter a critical sec¬ 
tion. The best method is to use semaphores, which are software flags main¬ 
tained by the system for coordinating the activities of several threads or 
processes. Semaphores are one of the most important forms of interprocess 
communication, and are discussed in Chapter 7. 

Using Multiple Threads in C 

You can successfully write multiple-thread applications in a high-level lan¬ 
guage such as C; however, you must follow a set of guidelines. This section 
summarizes these guidelines with reference to the Microsoft C compiler; if 
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you are using another language, the general principles still apply. Note also 
that the guidelines presented in this section refer primarily to the standard C 
library; Microsoft C (version 5.1) now supplies a special version of the run¬ 
time library and a set of header files specifically designed to support 
multiple-thread applications. When you use this version of the library, you 
should not call the standard functions DosCreateThread and DosExit, but 
rather the new C functions _beginthread and _endthread. Some of the 
other special guidelines you should follow if you are using this library ver¬ 
sion are given as parenthetical remarks throughout the discussion. See the 
documentation supplied with the compiler for further details. 

The first guideline is to use automatic or register variables to provide pri¬ 
vate, local storage for each thread. Automatic variables are those declared 
within the body of a function that either use the auto storage class specifier 
or have no storage class specifier. These variables are located within the 
stack, and as mentioned previously, each thread owns a separate stack. 
Variables declared using the register storage specifier are located in machine 
registers, and they are also private to a given thread, since the system main¬ 
tains a separate copy of the machine registers for each thread. 

To provide shared memory storage, you should use variables declared 
either outside the body of a function, or within a function using the static or 
extern storage class specifiers. These variables are located within the C pro¬ 
gram’s data segment, and are shared by all threads. 

Figure 6.3 provides an example of a C program that creates multiple 
threads, and illustrates the use of both private and shared data. This pro¬ 
gram starts two new threads, both of which execute the same C function: 
ThreadFunc. PrivateCount is declared as an automatic variable within the 
scope of ThreadFunc. Consequently, each of the two new threads has a pri¬ 
vate copy of this variable. When the program is run, both threads increment 
their own instance of PrivateCount (which has an initial value of 0) and dis¬ 
play the results; since the variable is local to each thread, both threads print 
the value 1 . ShareCount, however, is declared outside the scope of a func¬ 
tion and is therefore an example of shared data. The initial value of Share- 
Count is 0; after both threads increment this variable, the resulting value 
printed by main is 2, indicating that the variable is common to both 
threads. Note that the shared data item, ShareCount, is protected against 
simultaneous access by more than one thread by placing the instruction that 
manipulates it between calls to DosEnterCritSec and DosExitCritSec. 

Another guideline for writing multiple-thread C programs is that you 
must allocate the stack memory for each new thread as automatic data 
(which is located within the C stack, as explained above). Each C function 
begins with a routine that checks the value of the stack pointer and deter¬ 
mines whether sufficient stack space is available for the function. If you 
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Figure 6.3 

This is an example C program that creates multiple threads. You can 
prepare this program using the following command line. 


cl /G2 /Zp /Lp /Gs /F 1400 fig6_3.c 


#define INCL_D0S 
#define INCL_SUB 
#include <os2.h> 

#include <stdio.h> 
finclude <string.h> 

void far ThreadFunc (void); 


int ShareCount =0; /* SHARED variable, located in the data segment. */ 

void main () 

unsigned int ThreadOlID, Thread02ID; 

unsigned char ThreadOlStack [2048]; 

unsigned char Thread02Stack [2048]; 

char Message [16]; 

/* Start 2 threads executing the SAME function. */ 

DosCreateThread */ 

(ThreadFunc, /* Entry point. J 

&Thread01ID /* Receives thread ID. / 

ThreadOlStack + sizeof (ThreadOlStack)); /* Top of thread stack. */ 

DosCreateThread , 

(ThreadFunc, /* Entr Y P 01 ^‘ . Tn J, 

&Thread02ID /* Receives thread ID. */ 

Thread02Stack + sizeof (Thread02Stack)); /* Top of thread stack. */ 


DosSleep (1000L); 


/* Allow threads to run for 1 second. 


DosEnterCritSec (); , 

sprintf (Message, "ShareCount = %ld\r\n",ShareCount); 

DosExitCritSec (); 

VioWrtTTy (Message,strlen (Message),0); 

} /* end main */ 

void far ThreadFunc () 

int PrivateCount =0; /* This variable is private to each thread, 

char Message [16]; 

++PrivateCount; 

DosEnterCritSec (); 

++ShareCount; . . . „ J . 

sprintf (Message, “t>rivateCount = %ld\r\n",PrivateCount); 
DosExitCritSec (); 


VioWrtTTy (Message,strlen (Message),0); 
} /* end ThreadFunc */ 


FIGURE 6.3: A Cprogram that creates multiple threads 
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allocate stack space for a thread within the C data segment (by declaring the 
data externally or by using the static storage class specifier), then the stack- 
check routine will fail and will terminate the program, falsely reporting a 
stack overflow. Although you can defeat stack-checking for the functions 
within your source file using the /Gs command line option or the check- 
_stack (off) pragma, any standard C library functions called by your pro¬ 
gram still employ the stack-check routine and will cause the program to 
terminate. (Note that if you are using the multiple-thread version of the C 
library, you can use external or dynamically allocated data for the stack 
assigned to a new thread. The restrictions on stack location discussed here 
do not apply.) 

You also cannot use dynamically allocated memory (obtained through a 
C memory allocator such as malloc or through the OS/2 DosAllocSeg 
function) to provide a stack for a new thread. Such memory addresses are 
also outside of the C stack area and cause the stack-check routine to fail. 
(Also, some C library functions assume that the DS register equals the SS 
register; this assumption would become false if the thread’s stack was allo¬ 
cated by the DosAllocSeg function.) 

Note that the default stack size for a Microsoft C program is only 2 kilo¬ 
bytes, which is the minimum recommended stack allocation for a single new 
thread. Therefore, in a multiple-thread application you must enlarge the C 
stack size by using the /F n command line option, where n is a hexadecimal 
number specifying the desired number of bytes in the stack. The example 
program of Figure 6.3 can be prepared using the following command: 

cl /G2 /Zp /Lp IF 1400 fig6_3.c 

The /F 1400 option specifies a 5-kilobyte stack, which provides 2 kilobytes 
for each or the two threads plus 1 kilobyte for the main function. 

A final and important guideline for writing multiple-thread programs in 
C is to serialize access to C library functions that are not reentrant. Many of 
the library functions in the standard version of the Microsoft C compiler 
are nonreentrant, meaning that they can be executed by only a single thread 
at a given time. Table 6.2 lists the functions that are reentrant; you should 
assume that all other library functions are not reentrant. You must treat a 
call to a nonreentrant library function as a critical section of code, and pro¬ 
tect this area using one of the mechanisms discussed previously. The 
program in Figure 6.3 calls the nonreentrant sprintf function. All calls to 
this function are therefore embedded between calls to DosEnterCritSec and 
DosExitCritSec. This program also calls the strlen function; since this func¬ 
tion is reentrant, these calls are not protected. (Note that the comments 
given in this paragraph, as well as Table 6.2, do not apply to the multiple- 
thread version of the C library supplied with Microsoft C 5.1. If you use this 



Using Multitasking 


MULTITASKING 
OF PROCESSES 


abs 

memcpy 

strlen 

atoi 

meinicmp 

strlwr 

atol 

memmove 

strncat 

bsearch 

memset 

strncmp 

didir 

mkdir 

strnicmp 

getpid 

movedata 

strncpy 

halloc 

putch 

straset 

hfree 

rradir 

strrchr 

itoa 

segread 

strrev 

labs 

strcat 

strset 

Ifind 

strchr 

strstr 

Isearch 

strcmp 

strupr 

memecpy 

strcmpi 

swab 

memctir 

strcpy 

tolower 

merncmp 

striemp 

toupper 


Note: You must assume that all other C library functions are nonreentrant. 

TABLE 6.2: Reentrant Standard C Library Functions 

version of the library, you may freely call all C library functions—except 
signal—that are supported in the protected mode.) 


The terms program and process are often used interchangeably. A program, 
however, is a collection of instructions and data contained in an executable 
file and loaded into memory, whereas a process is an instance of the execu¬ 
tion of a program. A program, therefore, is a physical medium, and a pro¬ 
cess is an action or activity that uses this medium. In fact, a single program 
can be run simultaneously by more than one process. 

Recall from Chapters 1 and 2 that a screen group comprises one or more 
processes, and a process comprises one or more threads. Under OS/2, a 
process is also the basic unit of ownership. As mentioned in the last section, 
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a process owns resources and the threads belonging to this process share 
these resources. The following are among the resources that can be owned 
by a process: 

♦ A process ID 

♦ A local descriptor table (LDT; see Chapter 2) 

♦ One or more threads 

♦ Child processes 

♦ Code and data memory segments 

♦ File handles 

♦ Pipes 

♦ Queues 

♦ System semaphores 

♦ Device monitors (see Chapter 11) 

♦ Connections to dynamic-link libraries 

♦ A current disk and directory 

Each time a program is loaded and run, OS/2 begins a new process. This 
process can then begin additional processes in the same way that a thread of 
execution can begin additional threads. The relationships among these proc¬ 
esses, however, are different from those among multiple threads. All threads in 
a process are roughly equivalent; their associations are analogous to those 
among siblings in a family. Processes, however, form parent-child relation¬ 
ships; a process that spawns a new process is the parent and the new process is 
the child. A process can start multiple child processes, and each of the child 
processes can subsequently begin additional processes. Thus, the collection of 
processes in a given screen group form a genealogical tree structure. 

A branch of this tree that stems from a given process is known as a com¬ 
mand subtree of that process, and includes the child process and all the 
child's descendants. A command subtree is illustrated in Figure 6.4; 
the shaded processes form a command subtree belonging to process B. Note 
that this command subtree is identified by the ID of process E; a process ID 
refers both to the process itself and to the entire command subtree of which 
the process is the root. 

A command subtree has two important properties under OS/2. First, 
certain functions can be made to operate either upon a single child process 
or upon an entire command subtree; examples of such functions are 



FIGURE 6.4: An OS/2 command subtree 


DosCWait, DosKillProcess, and DosSetPrty (these: functions are described 
later in the section). When calling one of these functions, you must pass an 
action code or scope parameter to indicate whether the function is to affect 
a direct child process only or the entire command subtree of which the child 
is the root. For example, given the collection of processes illustrated in Fig¬ 
ure 6.4, process B could call DosKillProcess either to terminate process E 
only, or to simultaneously terminate processes E, G, H, and I. In both 
cases, process B would pass the ID for process E; the action code parameter 
would indicate the desired scope of the command. 

Note that a process cannot apply an API function to a command subtree 
that is not rooted in an immediate child. Therefore, for example, process B 
could not use DosKillProcess to terminate the processes in command subtree El 
(which consists of processes H and I). This limitation is in keeping with the gen¬ 
eral principle that a parent process should neither know nor depend upon the 
particular manner in which a child process is implemented. Specifically, a par¬ 
ent should not know whether a child process performs its task by itself or 
spawns child processes to assist in the task, and therefore it should not reference 
processes that are descendants of a child. Also, in conformance with this princi¬ 
ple, it is generally better to use the command subtree form of the API functions 
rather than the form that affects only the immediate child. For example, termi¬ 
nating an entire command subtree with DosKillProcess will produce uniform 
results whether the child process performs the entire task itself, or whether it 
has farmed out the task to multiple children. Likewise, when setting priorities 
using DosSetPrty, it makes sense to modify the priority of the entire subtree, 
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since in general you may be unaware how the specific functions are divided 
among the child process and its descendants (or even whether the child has 
descendants). 

The second important feature of a command subtree under OS/2 
is that the tree remains intact even if one or more of the individual processes 
that compose the tree terminate. For example, if process H in Figure 6.4 ter¬ 
minates, command subtree E remains intact, and therefore process B can 
control processes E, G, and I by using the command subtree form of the 
API functions. 

In addition to the flow of control from a parent to its descendant proc¬ 
esses just discussed, another important aspect of the relationship between 
parent and child processes is inheritance. When a process starts a child, the 
child acquires many of the features of the parent process. The following are 
among the features that a child inherits from its parent: 

♦ The parent’s screen group 

♦ The base scheduling priority of the parent 

4 A co Py of the parent’s environment strings (or whatever environ¬ 
ment strings the parent chooses to pass to the child; see the section 
on Program Entry under OS/2 in Chapter 2) 

♦ File handles that are open in the parent process, except those 
opened with the “no inheritance” option 

4 All handles open in the parent process for pipes, semaphores, and 
queues (see Chapter 7) 

Note, however, that a child process owns its own memory segments; when a 
child process is begun, the system sets up a new local descriptor table (LDT) 
for the segments belonging to this process. 

A child process normally performs a subsidiary task for a parent pro¬ 
cess. The inheritance of features provides the parent process a degree of 
control over the child, so that the child will perform as required to meet the 
needs of the parent. For example, a parent process can channel the input 
and output of a child process by redirecting the standard input and output 
file handles to refer to specific disk files. (The child process must, of course, 
perform 1/O through the standard handles; see the section on Using Direct 
Device Control in Chapter 4). The example program in Figure 6.5 
(described later in this section) uses this method to redirect the input of the 
SORT utility, which is run as a child process to sort the contents of a tempo¬ 
rary file. 
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Another important use for the inheritance mechanism is to pass a child 
process handles to open pipes, so that the parent and child can directly 
exchange data; the child process simply performs I/O through the standard 
handles, unaware that it is communicating with the parent process rather 
than with the console. The parent process can also set up pipes so that two 
child processes can directly exchange data. The use of pipes is described in 
Chapter 7. 

Using Multiple Processes 

If you are writing a multitasking application, you must decide whether to 
divide the program into multiple threads, multiple processes, or a combina¬ 
tion of these two multitasking components. The following are some of the 
differences between threads and processes. 

First, new threads can be started quickly (in as little as 3 milliseconds on 
a 6 MHz PC AT), and consume a moderate amount of system memory 
(approximately 1200 bytes each). To begin a new process, however, the sys¬ 
tem must load an executable file from a disk, set up a new local descriptor 
table, and perform other time-consuming tasks. The memory overhead of a 
process is also significantly greater than that for a thread. 

Also, all threads belonging to a process automatically share the memory 
segments and other resources of that process. Sharing resources among sep¬ 
arate processes, however, is more difficult and requires special procedures. 
For example, to share memory among processes you must allocate special 
shared segments; also, multiple threads can use simple RAM semaphores, 
whereas separate processes must use the more complex system semaphores. 
Shared memory and semaphores are discussed in Chapter 7. 

In general, therefore, threads are suitable for implementing asynchron¬ 
ous routines that are small, that are short-lived, or that must communicate 
and share resources intimately. Multiple processes, however, are more 
appropriate for implementing routines that are relatively large and have a 
long life (these programs can be loaded into memory only when they are 
required). Also, a routine that must remain isolated from the main program 
is best implemented as a separate process (such as a database package that 
does not allow the calling application to manipulate sensitive internal data 
structures). Finally, the multiple-process mechanism allows an application 
to call a separate executable utility—possibly developed by a different 
programmer—that cannot be run as an internal thread; for example, a pro¬ 
gram can run the OS/2 SORT utility as a child process (see Figure 6.5, dis¬ 
cussed later in this chapter). 

Table 6.3 lists alphabetically the OS/2 API functions that are useful for 
creating and managing multiple processes. 
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Function 

▼ 

Purpose 

▼ 

DosCWait 

Suspends the current thread until a child process 
terminates. Typically, you pass the ID of the child 
process, and DosCWait returns a result code when 
the process terminates; however, several other options 
are available. 

DosExecPgm 

Executes a program as a child process. You pass the 
name of the program, and the program arguments 
and environment; DosExecPgm returns the ID of the 
new process. The child process can be run 
synchronously or asynchronously. 

DosExit 

Terminates the current process; you must pass a code 
indicating that all threads in the process are to end, 
and pass a result code to be returned to the parent 
process. 

DosExitList 

Adds a routine to the list of functions that the system 
will execute when the current process terminates. You 
must pass the address of the routine. 

DosGetlnfoSeg 

Returns the ID of the current process, the ID of the 
parent of the current process, a flag indicating 
whether the current process is in the foreground, and 
a flag indicating whether the current process requires 
the real mode. 

DosGetPid 

Returns the ID of the current process and of the 
parent of the current process. 

BosGetPrty 

Returns the priority of thread number 1 in a specified 
process. You must pass the ID of this process. 

DosKillProcess 

Terminates either a single process or a process 
together with all its descendants; you must pass a 
code selecting one of these two options, plus the ID 
of the process. 

DosSetPrty 

Sets the base priority either of a single child process, 
or of a child process together with all its descendants; 
you must pass a code selecting one of these two 
options, plus the ID of the process. 


TAELE 6.3: OS/2 Functions for Managing Multiple Processes 
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Function 

V 

Purpose 

T 

DosSetSigHandler 

Installs a routine that receives control when a specific 
signal is sent to the process. You pass the address of 
the routine, a code for the specific signal, and a code 
for the action you want the system to take; the 
function returns the address of the former handler 
and its requested action. 


TABLE 6.3: OS/2 Functions for Managing Multiple Processes (continued) 


To begin a child process, call the DosExecPgm function. You must sup¬ 
ply this function with the name of the program to be loaded and run as a 
child process. You can specify either the fully qualified path name for the 
program (OS/2 will search the specified drive and directory), or you can 
give the simple program name (for example, PROG.EXE; in this case, OS/ 
2 will search the current directory plus all directories given by the PATH 
environment string). Note that you must include the extension (such as 
.EXE) in the program name. You must also supply a pointer to the program 
arg um ents (pass 0 if there are none), and the address of a set of environment 
strings (if you pass 0, the parent’s environment is inherited by the child pro¬ 
cess). If DosExecPgm fails, it returns the name of an “object” that contrib¬ 
uted to the failure of the function call, such as the name of a dynamic-link 
library file it could not find. 

You may use DosExecPgm to execute a program either synchronously or 
asynchronously (one of the parameters indicates the desired mode of execu¬ 
tion). If you execute a child process synchronously, the thread issuing this com¬ 
mand in the parent process is suspended until the child process terminates. 
When the child terminates, DosExecPgm returns a system termination code 
(indicating whether the termination was normal) and the result code specified 
by the last thread in the child process to issue the DosExit call. The synchronous 
execution option is provided primarily for compatibility with MS-DOS pro¬ 
grams and is not generally useful for OS/2 applications. 

If you execute the child process asynchronously, DosExecPgm returns 
immediately, passing back the process ID of the child. The child process 
subsequently runs concurrently with all the other processes in the system. In 
addition to normal synchronous and asynchronous execution of the new 
process, DosExecPgm provides two other modes of execution: one that 
allows a debugger to trace the child process, and another mode that runs the 
child process in the background (similar to the OS/2 DETACH command). 
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An asynchronous child process runs independently of the parent that 
created it; the parent process, however, has two important means for con¬ 
trolling a child process. First, the parent process can alter the priority of a 
child using the DosSetPrty function. Second, the parent can call 
DosKillProcess to terminate a child. Note that when using either of these 
two functions, you must pass the ID of the desired child process, plus a code 
indicating whether the function is to affect the child process alone or the 
entire command subtree stemming from the child (if one exists). 

An asynchronous child process can be brought back into synchroniza¬ 
tion with the thread that started it by calling the DosCWait function. At 
some point after starting an asynchronous child process, a parent may want 
to wait until the child has terminated and also may need to verify that the 
child executed successfully. DosCWait suspends the calling thread until 
the specified child process has terminated, and returns both a system termi¬ 
nation code (indicating whether the termination was normal) and the result 
code specified by the last thread in the child process to issue the DosExit 
call. Note that the termination and result codes are available only if the par¬ 
ent process passed the appropriate flags to DosExecPgm to request saving 
of this information. This command allows you to wait either for the child 
process alone to terminate, or for the child process and all its descendants to 
terminate. 

Note that the child process (as well as any process in the system) generally 
terminates by calling the DosExit function, unless it is terminated by 
another process through DosKillProcess, or it encounters a fatal error con¬ 
dition. Two functions are provided to help a process prepare for its demise. 
First, DosSetSigHandler allows a process to install a handler for one of sev¬ 
eral possible signals that it may be sent. One of these signals is sent to a pro¬ 
cess when it is terminated by another process through the DosKillProcess 
function. Thus, a process may install a routine that receives control when 
the process is killed and can perform final cleanup tasks. DosSetSigHandler 
also allows you to install handlers that receive control when the user presses 
Control-C or Control-Break, or when another process explicitly sends a sig¬ 
nal using the DosFlagProcess function. The OS/2 signal mechanism is dis¬ 
cussed as a form of interprocess communication in Chapter 7. 

Second, the DosExitList function allows a process to install one or more 
routines that receive control when the process terminates. Unlike DosSet¬ 
SigHandler, this function allows you to install more than one termination 
routine, all of which receive control—one at a time in an unpredictable 
order—when the process ends. Also, these routines are called no matter 
how the process ends, whereas a routine installed by DosSetSigHandler is 
called only if the process is killed though DosKillProcess. 
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Figure 6.5 provides an example of a C program that starts an asynchron¬ 
ous process to perform a subsidiary task. This program allows the user to 
enter a series of names in any order; it then runs the OS/2 SORT utility to 
sort and print the list of names in alphabetical order. 


/* 

Figure 6.5 

This program demonstrates redirecting the standard input file handle 
and running an asynchronous child process to perform a subsidiary task. 
Prepare this program using the following command line: 

cl /G2 /Zp /Lp fig6_5.c 

*/ 

#define INCL_DOS 
#include <os2.h> 

#include <stdio.h> 

#include <string.h> 

#include <process.h> 


void main () 

{ 

unsigned Error; 
unsigned short FileHandle; 
unsigned ActionTaken; 
unsigned BytesWritten; 
unsigned long NewPointer; 
char Name [30]; 
unsigned short Stdln = 0; 
unsigned short SaveStdln; 
char ObjectName [13]; 

RESULTCODES ExecResult; 
RESULTCODES WaitResult; 
unsigned ProcessID; 


Error = DosOpen 

("@TEMP@.@@@", 
&FileHandle, 

&ActionTaken, 

0L, 

0 , 

0x0012, 

0x0042, 

0L); 

if (Error) 

{ 

fprintf (stderr,"Error 
exit (1); 

> 


/* For saving API error code. * 
/* Used by API file functions. * 
/* Used by DosOpen. * 
/* Used by DosWrite. * 
/* Used by DosChgFilePtr. * 
/* Stores an input name. * 
/* File pointer for standard input. * 
/* Pointer for saved standard input file.* 
/* Used by DosExecPgm. * 
/* Used by DosExecPgm and DosCWait. * 
/* Used by DosExecPgm. * 
/* Used by DosCWait. * 
/* Used by DosCWait. * 

/* Open a temporary file. * 

/* File name. * 
/* Variable to receive file handle. * 
/* Variable to receive action code. * 
/* Initial allocation size. * 
/* File attribute: normal file. * 
/* Create new or truncate existing file. * 
/* Share, read, and write access. * 
/* Must be 0. * 


%d opening temporary file.\n", Error); 


/* Input list of names fjrom user. 

printf ("Enter list of names - press Return after each name\n"); 

printf ("<just press Return to terminate list and begin sort>\n"); 


/ 


FIGURE 6.5: A C program that redirects a standard fde handle and starts an asynchronous child process 





200 


Programmer’s 
Guide to OS/2 
CH6 


gets (Name); 

while (Name [0] != '\0') 

{ 

strcat (Name,"\r\n"); 

DosWrite 

(FileHandle, 

Name, 

strlen (Name), 
SBytesWritten); 

gets (Name); 

} 

DosChgFilePtr 

(FileHandle, 

0L, 

0 , 

SNewPointer); 

SaveStdln = Oxffff; 
DosDupHandle 
(Stdln, 

SSaveStdln) ; 


/* Get a name. 


/* Add a CR/LF. 

/* Write names to temporary file. 

/* File handle from DosOpen. 

/* Pointer to buffer to write. 

/* Buffer length. 

/* Receives bytes written. 

/* Get another name. 

/* Rewind the file. 

/* File handle from DosOpen. 

/* Distance to move file pointer. 

/* Move from beginning of file. 

/* Receives new pointer location. 

/* Save a handle to standard input. 

/* Existing file handle. 

/* New file handle. 


/* Redirect standard input to the temporary file. 
DosDupHandle (FileHandle,&StdIn); 


/* Execute the OS/2 SORT utility as a child process, which inherits 
/* the redirected standard input. 

Error = DosExecPgm 


(ObjectName, /* 

sizeof (ObjectName), /* 

2 ' /* 

0 , /* 

0 , /* 

&ExecResult, /* 

"SORT.EXE"); /* 


Receives name of file that failed. 
Size of buffer to receive file name. 
Execute asynchronously; save code. 
NULL arguments. 

Pass parent's environment. 

Receives process ID. 

Name of program to execute. 


if (Error) 

{ 

printf ("Error %d executing child process\n",Error); 
exit (1); 

} 


DosClose (FileHandle); /* Temporary file no longer needed. */ 

/* Restore standard input handle to original source. */ 
DosDupHandle (SaveStdln,&StdIn); 

DosClose (SaveStdln); /* Finished with standard input save handle. */ 

/* The code for the remainder of the parent process would go here. */ 

/* The sort process is executing concurrently, and the standard input */ 
/* handle has been restored to its original source. */ 

/* Wait for child process to end before deleting the temporary file */ 
/* and terminating! */ 


DosCWait 

(1/ /* Wait for child and all descendants.*/ 

0, /* Wait for child termination. */ 


FIGURE 6.5: A C program that redirects a standard file handle and starts an asynchronous child process 
(continued) 
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&WaitResult, /* Receives OS/2 and process codes. */ 

&ProcessID, /* Receives process ID. */ 

ExecResult.codeTerminate); /* ID of child process. */ 

if (WaitResult.codeTerminate == 0) /* Test for normal termination. */ 

printf ("\n\nSort operation complete.\n"); 
unlink ("@TEMP@.@@@"); 
exit (0) ; 

> 

else 

printf ("\n\nSort operation terminated abnormally.\n"); 
exit (1); 

> 

> /* end main */ 


FIGURE 6.5: A C program that redirects a standard file handle and starts an asynchronous child process 
(continued) 


The program first opens a temporary file using the DosOpen command. 
The file is assigned the name @TEMP @. @ @ @. The file attribute (param¬ 
eter number 5, given a value of 0) states that the file has the normal attribute 
(that is, it does not have a special attribute such as read-only or hidden). The 
open flag (the sixth parameter, given the value 0x0012) specifies that if the 
file exists, it should be truncated, and if it does not exist, a new file should 
be created. The open mode (the seventh parameter, given the value 0x0042) 
causes the file to be opened with read and write access granted to both the 
calling process and to other processes that may share the file. The returned 
file handle is stored in the variable FileHandSe. 

The program next accepts a series of names from the user and writes 
them—one per line—to the temporary file, using the API function 
DosWrite. After the last name has been written, the OS/2 file pointer is 
restored to the beginning of the file by calling the function DosChgFilePtr. 
The distance (the second parameter) and the move type (the third parame¬ 
ter) are both set to 0 to specify a distance of 0 from the beginning of the file. 

The OS/2 SORT utility reads unsorted lines from standard input and 
writes the lines in sorted order to standard output. Before running SORT- 
.EXE as a child process, the example program temporarily redirects the 
standard input handle to point to the temporary data file containing 
the unsorted names. Since a child process inherits the open file handles of its 
parent, SORT automatically obtains its input from the temporary file. The 
standard output handle is not redirected; therefore, the output from SORT 
normally appears directly on the screen (unless standard output has been 
redirected by an ancestor of the example program). 





202 


Programmer’s 
Guide to OS/2 
CH6 


The temporary redirection of standard input is performed through the 
following series of steps: 

1. The existing standard input handle is duplicated in a temporary 
file handle (SaveStdln) using the function BosBupHandle, so that 
it can be restored after the child process is started (otherwise, the 
program would lose its link with the initial source of standard 
input). The first parameter to BosDupHandle is the handle to be 
duplicated, and the second parameter is the handle that is forced 
to point to the same file as the handle given by the first parameter. 
Note that the first parameter is a direct value, and the second 
parameter is the address of a variable that contains the appropriate 
value. If a value of OxFFFF is assigned to the variable passed as 
the second parameter (as in this example), the system duplicates 
the handle in the first available file handle , and assigns this handle 
to the parameter (in this case, to SaveStdln). 

2. DosDupHandle is called again to force the standard input handle 
to point to the temporary file (@TEMP@.@@@, accessed 
through the handle FileHandle). 

3. The child process is started, which inherits the current state of the 
file handles. Therefore, during the execution of this process the 
standard input handle points to the temporary file. 

4. After the child process is started, the parent process calls BosClose 
to close the handle to the temporary file (FileHandle), since this 
handle is no longer needed. 

5. The program calls BosBupHandle once more to restore the origi¬ 
nal source for the standard input handle, and then closes the han¬ 
dle stored in SaveStdln. Note that during the remainder of the 
program, standard input will point to its original source (typically 
the keyboard). 

SORT.EXE is executed as an asynchronous child process by calling 
BosExecPgm. The third parameter is a flag indicating the desired mode of 
execution; the program passes the value 2, which tells the system to run the 
child process asynchronously and to save the result code (specified by the 
child process on its last call to BosExit) so that this code can be obtained at a 
later time by calling BosCWait. The fourth parameter is the address of the 
program argument string and is given a value of 0 indicating that there are 
no arguments. The fifth parameter is the address of the set of environment 
strings; this parameter is also given the value 0, which causes the system to 
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pass an unaltered copy of the parent’s environment. The last parameter is 
the name of the program that is to be run as a child process; the simple pro¬ 
gram name (SORT.EXE) is supplied rather than the full path name so that 
the system will use the current value of the PATH variable to find the pro¬ 
gram file. The ID of the child process that is returned by DosExecPgm is 
stored in the field 

ExecResult.codeTerminate 

(it will be used later in the program to call DosCWait). 

When control returns from DosExecPgm, the parent process can per¬ 
form other tasks while the sort operation runs concurrently (the simple 
example program has nothing more to do at this point; however, a typical 
application program could continue processing). The final task of the par¬ 
ent process is to delete the temporary file that it created. Before deleting this 
file, however, the parent must make sure that the child process has com¬ 
pleted successfully and that the file is thus no longer needed. It therefore 
calls DosCWait to suspend itself until the child process has terminated. The 
first parameter to DosCWait is an action code\ the value 1 is passed, which 
causes the system to wait for the child process and any descendants of the 
child. The second parameter is the wait option and is given a value of 0, 
which tells the system to wait until the process has terminated (rather than 
returning immediately). The final parameter is the process ID; the program 
passes the ID value that was returned by the call to DosExecPgm. Before 
deleting the temporary file, the parent process examines the terminate code 
that is returned in the codeTermmate field of the WaltResult structure (the 
address of this structure is passed as the third parameter); this code indi¬ 
cates whether the child process terminated successfully. 

Note that to illustrate the use of the API, all file operations in this pro¬ 
gram are performed through OS/2 functions. You could also perform these 
operations using C library functions (the low-level functions, such as open 
and write, would be the most appropriate for this application). 


A screen group (or session) is defined as a collection of processes that share 
a single virtual screen, keyboard, and mouse. The basic features of OS/2 
screen groups were described in Chapter 1, in the section on The Structure 
of OS/2. Screen groups are the highest level of multitasking under OS/2, 
and are normally managed directly by the user in one of several ways. First, 
the user can start a new screen group through the program selector of the 
session manager, or by invoking the START command from the operating- 
system command line. Also, the user can terminate a screen group through 
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the EXIT command (a screen group may automatically terminate if it was 
started from the session manager and its last process has completed). 
Finally, the user can select a screen group to bring into the foreground 
through the Alt-Escape hotkey, or by choosing a program from the ses¬ 
sion manager. 

Most applications—including quite complex ones—can be written to run 
as one or more processes within a single screen group; in fact, the Presenta¬ 
tion Manager and all of the compatible programs it manages run within a 
single screen group. OS/2, however, provides several API functions that 
allow application programs to directly create and manage multiple screen 
groups. The unique feature of a process that is started in a separate screen 
group is that the system automatically isolates its screen, keyboard, and 
mouse I/O from that belonging to processes in other screen groups (see the 
section on Protected Mode Screen Groups in Chapter 1). 

A detailed discussion on managing multiple screen groups from an appli¬ 
cation program is beyond the scope of this book. However, to complete the 
treatment of multitasking, this section briefly describes the organization of 
screen groups and summarizes the API functions that manage them. 

Multiple screen groups are organized much like multiple processes. A 
new screen group created by an application program usually becomes a 
child of the original screen group (it is also possible to create an unrelated 
screen group). Also, like processes, a parent screen group is provided sev¬ 
eral methods for controlling the child screen groups it has created (to be 
described shortly). 

Table 6.4 summarizes the basic features of the API functions for creating 
and managing screen groups from an application program. 

The function DosStartSession begins a new screen group and begins a 
new process running in this screen group. This function therefore represents 
an exception to the general principle that a child process inherits the screen 
group of its parent. One of the fields passed to this function indicates 
whether the new screen group is to be a child (that is, related) or indepen¬ 
dent (not related). The screen group must be related for the parent to be able 
to use the DosSelectSession, DosSetSession, and DosStopSession API 
functions to control the child screen group. The new screen group can be 
started either in the foreground or in the background. 

The function DosSelectSession enables you to place either the current 
screen group, or a child of the current screen group, into the foreground. 
Note that either the current screen group or one of its descendants must be 
in the foreground when this function is called. 
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Function 

V 

Purpose 

V 

DosGetlnfoSeg 

Returns the current foreground screen group, the 
maximum number of screen groups, the ID of the 
current screen group, and whether the current screen 
group is in the foreground. 

DosSelectSession 

Places the specified screen group in the foreground; you 
must pass the ID of the desired screen group (which may 
be that of either the current screen group or of one of its 
child screen groups). 

DosSetSession 

Sets the operational characteristics of a child screen 
group; you must pass the ID of the screen group plus the 
address of a structure that indicates the desired options. 

DosStartSession 

Starts a process in a new screen group; you must pass the 
address of a structure containing data for creating the 
new screen group. The function returns the new screen 
group’s ID. 

DosStopSession 

Terminates an individual child screen group, or all child 
screen groups; you must pass a flag indicating one of 
these two options and, if applicable, the ID of the child 
screen group. 


TABLE 6.4: OS/2 Functions for Managing Multiple Screen Groups 


DosSetSession allows you to specify the following two options for a 
child screen group: 

♦ You can specify whether the screen group can be selected from the 
session manager. 

♦ You can establish or break a bond with a child screen group, 
whereby the child is brought to the foreground whenever the par¬ 
ent is selected from the session manager. 

Finally, you can use the function DosStopSession to terminate a child 
screen group that was created with DosStartSession. 
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Chapter 6 introduced the topic of multitasking under OS/2, and 
described how to create and manage multiple processes and threads of 
execution. Although a protected mode operating system isolates indi¬ 
vidual processes, these processes typically share common resources, 
such as memory segments and peripheral devices. Also, separate pro¬ 
cesses must often work together as the components of an integrated 
software system. Accordingly, OS/2 provides a large set of functions 
for managing interprocess communication; these functions allow 
processes to avoid mutual interference when accessing shared 
resources, and they also provide channels for cooperating processes to 
synchronize their activities and exchange data,, Note that the forms of 
interprocess communication discussed in this chapter can be used for 
communicating among separate threads as well as among separate 
processes (thus, the term process in the expression interprocess com¬ 
munication is used in a general sense). 
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When programming under a preemptive multitasking operating system, 
you must remember that a given thread can be suspended-—and another 
thread receive control—between any two distinct machine instructions. 
Also, when a thread is executing a given instruction, you cannot predict 
what any other thread is doing, since all threads execute asynchronously. 
Because you cannot assume when a thread will be preempted or what 
another thread is currently doing, you must make explicit use of 
interprocess communication to coordinate access to shared resources and to 
synchronize program tasks. 

Another important implication of programming under a multitasking 
system is that while a thread is waiting to access a shared resource or paus¬ 
ing execution for any other reason, it should not consume processor cycles. 
Under a single tasking system, it is acceptable for a program to execute a 
loop while waiting for an event (perhaps repeatedly testing some flag or 
reading an I/O port). This practice is known as busy waiting , and under a 
multitasking system it needlessly wastes CPU time and decreases the effi¬ 
ciency of the other processes. When using the interprocess communication 
services of OS/2, however, a waiting thread blocks (meaning that it goes 
into the blocked thread state described in Chapter 6, and does not consume 
processor cycles). When the desired event occurs, the thread is reawakened 
by the system and continues execution; a thread that is activated by an 
external event and does not waste time testing for the occurrence of this 
event is termed event-driven (hardware interrupt handlers are an example 
of event-driven code under MS-DOS). Note that other OS/2 services that 
may suspend thread execution, such as KbdCharln or DosSleep, also use 
blocking rather than busy waiting. 

The following forms of interprocess communication are discussed in this 
chapter: 

♦ Shared memory 

♦ Semaphores 

♦ Pipes 

♦ Queues 

♦ Signals 


Table 7.1 summarizes the OS/2 API functions for allocating and managing 
shared segments of memory. Note that the table gives only the uses for these 
functions that apply specifically to shared memory (DosAllocSeg and 
DosFreeSeg, for example, are also used for nonshared memory). 
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Function 

v 

Purpose 

DosAllocHuge 

Allocates a huge block of giveaway (or local) shared 
memory (that is, an allocation of more than one 
64-kilobyte segment). You must pass a flag indicating 
that the segment is shareable through DosGiveSeg. 

See the description of this function in Chapter 8. 

DosAllocSeg 

Allocates a giveaway (or local) shareable memory 
segment. You must pass the size of the requested 
segment, and a flag indicating that the segment is 
shareable through DosGiveSeg. DosAllocSeg returns 
a selector that is valid for the current process. 

DosAllocShrSeg 

Allocates a named (or global) shared memory 
segment. You must pass the name and size of the 
requested segment, and the function returns a 
selector that is valid for the current process. 

DosFreeSeg 

Takes away access from the current process to a 
shared memory segment (allocated through 
DosAllocHuge, DosAllocSeg, or DosAllocShrSeg). 

You must pass this function the segment selector. 

When all processes have relinquished access to the 
segment by calling this function, the memory is 
deallocated. 

DosGetShrSeg 

Grants the current process access to a named (or 
global) shared memory segment (allocated through 
DosAllocShrSeg). You pass the name of the shared 
memory segment, and the function returns a selector 
that is valid within the current process. 

DosGiveSeg 

Grants another process access to a giveaway (or 
local) shared memory segment (allocated through 
DosAllocSeg or DosAllocHuge). You pass the 
selector returned by DosAllocSeg and the ID of the 
recipient process; DosGiveSeg returns a selector that 
is valid within the recipient segment. 

DosMemAvail 

Returns the size of the largest block of free memory 
(this value is subject to change at any time). 


TABLE 7.1: OS/2 Functions for Managing Shared Memory 
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As explained in Chapter 2, each process has its own local descriptor table 
(LDT) containing descriptors for all code and data segments owned by the 
process. It is therefore not normally possible for one process to access the 
memory segments owned by another process. The operating system, how¬ 
ever, can place descriptors referring to the same memory segment in the 
descriptor tables of more than one process. (An additional descriptor refer¬ 
ring to the same segment as an existing descriptor is known as an alias.) 
Alias segment descriptors form the basis for sharing memory under OS/2. 

Shared memory is potentially the most efficient and flexible method for 
exchanging data between processes, because once the data is written to 
memory it does not need to be copied or otherwise processed by the operat¬ 
ing system, and all data in the segment can be freely accessed by any sharing 
process. However, as you will see shortly, the full burden of managing 
shared memory segments falls upon the processes that use them; these pro¬ 
cesses must explicitly allocate and deallocate the segments, they must obtain 
and communicate segment names or selectors, and they must serialize access to 
shared data. When using shared memory, there are few standard protocols; 
rather, the sharing processes must define and follow their own protocols. 
Therefore, for exchanging small amounts of data, one of the more “prepack¬ 
aged” forms of interprocess communication, such as pipes or queues, may be 
more convenient and efficient. 

There are two basic forms of shared memory: named (or global) and 
giveaway (or local). When a named shared memory segment is allocated, it 
is assigned a global name; any process in the system that knows this name 
can gain access to the segment. When a giveaway shared memory segment is 
allocated, the system returns a selector that is valid only within the calling 
process; this process must then obtain an additional selector for any 
other process that is to share the segment, and then communicate this selec¬ 
tor to the other process. Thus, a named shared memory segment is auto¬ 
matically available to all processes that know the name, whereas a giveaway 
shared memory segment must be explicitly passed from one process to 
another. 

Named Shared Memory 

A named shared memory segment is allocated through the function Dos- 
AllocShrSeg. You must pass this function the desired segment size in bytes 
(a value from 0 to 65,535, where 0 indicates a size of 65,536 bytes). You 
must also pass the name you want assigned to the shared segment; note that 
this name follows the file-naming conventions and must begin with the 
string \SHAREMEM\. Thus, all shared memory segments are in the ficti¬ 
tious \SHAREMEM directory (not a real directory, since the segments exist 
in memory and not on a disk). A process can allocate up to 30 shared mem¬ 
ory segments. 
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DosAllocShrSeg returns a selector for the allocated segment that is valid 
only within the calling process. Before a second process can address this seg¬ 
ment, it must call DosGetShrSeg to obtain its own segment selector. The 
second process must pass DosGetShrSeg the full name of the shared mem¬ 
ory se gm ent (which it must know in advance or somehow obtain from the 
first process at run-time). DosGetShrSeg creates an alias selector for the 
shared memory segment, places this selector in the local descriptor table of 
the second process, and then returns the selector. Any number of subse¬ 
quent processes can follow this same procedure, each process obtaining its 
own selector to access the common shared segment. 

When a process has finished using the shared memory, it should call 
DosFreeSeg to relinquish its access to the segment. Each time a process 
obtains access to a shared segment (through DosAllocShrSeg or DosGet¬ 
ShrSeg), the system increments a reference count for the segment, and each 
time a process calls DosFreeSeg, the system decrements the reference count. 
The memory is not actually deallocated until the reference count becomes 
zero (at this time, the shared segment is “deleted” from the \SHAREMEM 
directory). 

Note that access to memory shared by several processes is usually coordi¬ 
nated by using semaphores. Figure 7.1, described later in this chapter in the 
section on semaphores, provides an example of using named shared 
memory. 

Giveaway Shared Memory 

Giveaway shared memory segments are allocated using the standard OS/2 
memory allocation function, DosAllocSeg. This function can be used to 
allocate normal private segments or segments that can subsequently be 
shared with other processes. To obtain a segment that can be shared, you 
must set bit 0 of the allocation flags (the third parameter passed to Dos¬ 
AllocSeg). You must also pass the desired segment size in bytes as the first 
parameter (a value from 0 to 65,535, where 0 indicates a size of 65,536 
bytes). (Note that you can likewise obtain giveaway shared memory by call¬ 
ing DosAllocHuge, which allocates multiple-segment blocks of memory. 
This function accepts the same allocation flags parameter, and is discussed 
in Chapter 8.) 

DosAllocSeg returns a selector that is valid only within the current pro¬ 
cess. To grant access to this segment to a second process, you must call the 
function DosGiveSeg. You need to pass DosGiveSeg the selector returned 
by DosAllocSeg plus the ID of the second process-, DosGiveSeg then returns 
a selector that is valid within the second process. Before the second process 
can address the shared memory, you must send it this selector. Note, there¬ 
fore, that before you can share a giveaway segment, two items of informa¬ 
tion must be exchanged between the sharing processes: the first process 
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must obtain the ID of the second, and the second process must obtain its 
selector from the first. This initial exchange of data can be accomplished 
using some other form of interprocess communication. For example, you 
might allocate a small named shared segment for exchanging all such data 
throughout the program. Also, giveaway shared memory segments are 
often used in conjunction with queues; the functions for opening and writ¬ 
ing to queues allow you to exchange the process ID and memory selector as 
required to share the memory segments that contain the queue elements. 
See Figures 7.4 and 7.5, in the section on queues, for an example of using 
giveaway shared memory. 

Note that once a process has passed access to a giveaway segment to a 
second process, the second process can give access to a third process, and so 
on. When a process is done using a shared memory segment, it should relin¬ 
quish its access to this segment by calling DosFreeSeg. In the same manner 
as named shared memory, the system deallocates the memory when the ref¬ 
erence count becomes 0. 

The giveaway shared memory mechanism, although slightly less conven¬ 
ient than named shared memory, is faster and also offers greater security 
(the memory can be accessed only by processes that explicitly arrange to 
share the segments). Giveaway memory is especially suitable for applica¬ 
tions that require a large number of segment allocations. (Named shared 
memory would demand that the application generate and process a unique 
name string for each segment that is allocated.) 


Table 7.2 lists the basic OS/2 functions for managing semaphores. A sema¬ 
phore is a software flag used to coordinate the actions of multiple threads. 
Unlike other forms of interprocess communication, semaphores do not 
transfer data from one process to another, but rather allow separate threads 
to synchronize their activities by exchanging simple “stop” and “go” infor¬ 
mation. A semaphore is normally in one of two states: set (also called 
owned), or clear (also known as unowned or free ; a thread that “owns” a 
semaphore is simply one that has set it, and not necessarily one that created 
or has exclusive access to the semaphore). A set semaphore generally indi¬ 
cates that a thread should stop and wait for the semaphore to be cleared by 
another process, and a clear semaphore generally means that the thread can 
continue. This section discusses the two types of semaphores provided by 
OS/2, and the specific ways semaphores may be used by multiple-thread 
applications. 

OS/2 supports two types of semaphores: RAM semaphores and system 
semaphores. A RAM semaphore is a simple 4-byte data structure located 
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Function 

Purpose 

DosCloseSem 

Closes a system semaphore. You must pass the handle 
of the system semaphore; the system deletes the 
semaphore when it has been closed by all processes 
that have opened it. 

DosCreateSem 

Creates a system semaphore; you must pass the name 
to be assigned to the semaphore and a flag indicating 
whether access is to be exclusive to the calling 
process. The function returns a semaphore handle 
that can be used only by the current process; other 
processes must obtain their own handles by calling 
DosOpenSem. 

DosMuxSemWait 

Blocks the calling thread until one or more of the 
specified semaphores is cleared. You must pass a list 
of the semaphores (up to 16) and the maximum 
length of time the thread will wait for one of these 
semaphores to be cleared. The function returns the 
index of the first semaphore that is cleared. 

DosOpenSem 

Opens a system semaphore that has already been 
created by another process through the 

DosCreateSem function. You pass the full name of 
the semaphore, and DosOpenSem returns a 
semaphore handle that can be used by the calling 
process. 

DosSemClear 

Unconditionally clears the specified semaphore and 
restarts any processes blocked on this semaphore; 
you must pass the semaphore handle. 

DosSemRequest 

Waits until the specified semaphore is cleared (if it is 
not already clear) and then sets this semaphore. You 
pass the semaphore handle and the maximum length 
of time the thread will wait for the semaphore to be 
released. 

DosSemSet 

Unconditionally sets a semaphore; you must pass the 
semaphore handle. 


TABLE 12: OS/2 Functions for Managing Semaphores 
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Function 

Purpose 



DosSemSetWait 

Sets the specified semaphore and then blocks the 
current thread until another thread clears the 
semaphore. 

DosSemWait 

Waits for the specified semaphore to be cleared 
(returns immediately if the semaphore is already 
clear). 


TABLE 7.2: OS/2 Functions for Managing Semaphores (continued) 


within memory owned by the process that uses it. A RAM semaphore does 
not have a name, but rather is identified solely by its address. A system sem¬ 
aphore, however, is kept within memory owned by the kernel, and, unlike a 
RAM semaphore, it must be created through an explicit API function call 
(DosCreateSem). A system semaphore is assigned a global name, and can 
be accessed by any process that knows this name. 

RAM semaphores are considerably faster than system semaphores. (For 
example, on a 6 MHz PC AT, setting a free semaphore requires approxi¬ 
mately 100 microseconds for a RAM semaphore and 350 microseconds for 
a system semaphore. System calls that manipulate RAM semaphores oper¬ 
ate within the context of the calling process, whereas API calls for system 
semaphores must switch into kernel mode, which involves the time- 
consuming call gate mechanism). Because of their speed, and because you 
do not need to use OS/2 function calls to create them, RAM semaphores 
may be the preferable mechanism for use within a single process. 

For coordinating the activities of several processes, however, system 
semaphores offer two important advantages. First, system semaphores are 
easily shared by multiple processes, since any process that knows a sema¬ 
phore’s name can gain access to it (to share a RAM semaphore, you would 
first have to set up a shared memory segment and then communicate the 
address of the semaphore within this segment). Second, if a process that has 
set a semaphore terminates without clearing it, all threads in other processes 
waiting for this semaphore are released and are returned an error message 
indicating that a process died while holding the semaphore. This provision 
is important for preventing deadlock when a semaphore is shared by more 
than one process. 
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The procedures for using these two types of semaphores are similar. The 
following discussion of the basic steps for creating and managing sema¬ 
phores points out the differences. 

The first step is to create the semaphore. If you are using a RAM sema¬ 
phore, you need to allocate a 4-byte area of memory and initialize this memory 
to 0. You must save the far address (selector and offset) of the semaphore, since 
this address will be used as a handle to reference the semaphore in subsequent 
API function calls. If you are using a system semaphore, you must create the 
semaphore by calling DosCreateSem. The first parameter to this function is a 
flag indicating whether you wish the owning process to have exclusive access to 
the semaphore; for the uses discussed in this section, you should pass a value of 
7, which denies exclusive access. The third parameter is the global name to be 
assigned to the semaphore; this name must follow OS/2 file-naming conven¬ 
tions and begin with the prefix \SEM\. (Just as named shared memory exists in 
the fictitious \SHAREMEM directory, system semaphores are kept in the ficti¬ 
tious \SEM directory.) 

DosCreateSem returns a semaphore handle that is valid within the cur¬ 
rent process only ; this handle is used to reference the semaphore in subse¬ 
quent API function calls. Once a process has created a system semaphore, a 
second process can gain access to this semaphore by calling DosOpenSem. 
DosOpenSem accepts the name of the semaphore and returns a handle that 
is valid within the second process. Therefore, either the second process must 
know the name of the semaphore in advance, or the name must be passed 
from the first process to the second using some form of interprocess com¬ 
munication at run-time. Note that a newly created semaphore is initialized 
to the clear {unowned) state. 

Most of the API functions for managing semaphores require you to pass 
a semaphore handle. For a RAM semaphore, the handle is simply the far 
address of the semaphore (within a memory segment owned by the pro¬ 
cess). For a system semaphore, you should use the handle returned by 
DosCreateSem or DosOpenSem. Semaphores can be used in many ways; 
this section discusses two of the most important uses: serializing access to a 
critical section of code, and flagging the occurrence of an event. 

Protecting Critical Sections of Code 

The necessity for protecting critical sections of code was discussed in Chap¬ 
ter 6 (in the section entitled Using Multiple Threads). A critical section of 
code is one that manipulates a resource that must be accessed by only one 
thread at a time. To serialize access to the resource managed by a critical sec¬ 
tion, you can call the function DosSemRequest at the beginning of the 
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section, specifying a given semaphore, and then call DosSemClear at the 
end of this section, specifying the same semaphore. For example, the fol¬ 
lowing code protects a critical section of code that accesses nonshareable 
resource A: 

DosSemRequest (SemHandle, - 1L); 

/* Critical section of code, which accesses nonshareable */ 

/* resource A. */ 

DosSemClear (SemHandle); 

DosSemRequest waits, if necessary, for the specified semaphore to be cleared 
and then immediately sets the semaphore. (The second parameter passed to 
DosSemRequest specifies the length of time the thread will wait for the sema¬ 
phore to be cleared; - 1 indicates that the thread will wait indefinitely, which is 
the appropriate option for protecting a critical section of code.) Thus, the cur¬ 
rent thread cannot enter the critical section of code if another thread has 
already entered this section of code or any other section of code protected 
with the same semaphore . At the end of the critical section, DosSemClear 
clears the semaphore so that other threads become free to enter sections of 
code protected with the same semaphore. Note that to effectively serialize 
access to resource A, you must use the same semaphore to protect all sec¬ 
tions of code that manipulate resource A. (Remember that when a sema¬ 
phore is created, it is initialized to 0—either by OS/2 for a system 
semaphore, or by you for a RAM semaphore. Therefore, the first thread to 
call DosSemRequest for a given semaphore is always allowed to enter the 
critical section.) 

As another example, semaphores can be used to serialize access to non¬ 
reentrant C library functions called by more than one thread in a single pro¬ 
cess. The program in Figure 6.3 surrounded calls to the nonreentrant 
sprintf function with calls to DosEnterCritSec and DosExitCritSec, as in 
the following lines: 

DosEnterCritSec (); 

sprintf (Message,“ShareCount = °/old\r\n”,ShareCount); 

DosExitCritSec (); 

Note that this code has the effect of arbitrarily suspending all threads within 
the process except the current thread. Semaphores, however, offer a finer 
level of control; by using semaphores, you could suspend only those threads 
that are about to call sprintf, as in the following lines: 

DosSemRequest (SprintfLock, - 1L); 

sprintf (Message,“ShareCount = %ld\r\n”,ShareCount); 

DosSemClear (SprintfLock); 
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Note that SprintfLock is the handle to a semaphore created specifically to 
protect the sprintf function. You must protect all calls to sprintf within any 
of the threads of a given process using this same semaphore. 

Another example of using semaphores to protect a critical section of 
code is provided by the program of Figure 7.1, described later in this 
section. 

What happens when multiple threads are waiting for a given semaphore, 
and this semaphore is cleared? Since DosSemRequest releases the waiting 
thread upon clearing of the semaphore, it would seem that all wait¬ 
ing threads would be released simultaneously like a row of racehorses, and 
that the protection of the critical resource would be breached. This situation 
does not arise, however, because the release of waiting threads is level- 
triggered, meaning that the semaphore must be clear at the time the thread 
is actually scheduled to run (in other words, if the semaphore is reset before 
the thread has a chance to run, the thread will not be released). When the 
semaphore is cleared, all waiting threads become eligible to run; however, 
since only one thread can run at a given time, only the thread with the high¬ 
est priority actually begins running. This thread resumes executing Dos¬ 
SemRequest (it was interrupted in the middle of this function), which 
immediately resets the semaphore. Therefore, the other waiting threads 
become blocked again, before having a chance to run. Accordingly, each 
time the semaphore is subsequently cleared, only the highest-priority thread 
is released. 

Flagging Events with Semaphores 

Another common use for semaphores is for one thread to flag the occur¬ 
rence of an event to another thread. For example, a given thread may serve 
to read characters from a device; this thread may need to flag one or more 
other threads when a complete buffer full of characters has been received 
and is ready to process. You can use semaphores to perform this signaling 
function through the following typical sequence of steps. First, the thread 
that processes the characters (which needs to receive the signal) calls Dos- 
SemSet, which unconditionally sets the specified semaphore. This thread 
then starts a second thread, which begins reading characters from the 
device. When the second thread has received a complete buffer of charac¬ 
ters, it calls DosSemClear, specifying the same semaphore as the call to Dos- 
SemSet; the transition of this semaphore from set to clear serves as a signal 
that the buffer is full. 

In the meantime, the first thread can perform other tasks; however, 
when this thread is ready to process the buffer, it calls DosSemWait, specify¬ 
ing the same semaphore used by the prior call to DosSemSet. DosSemWait 
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blocks the thread until the semaphore is cleared (indicating that the buffer is 
full); if the semaphore is already clear, DosSemWait returns immediately. 
Unlike DosSemRequest, DosSemWait does not set the semaphore. Note 
that several threads can call DosSemWait to wait for a single semaphore to 
be cleared. When the semaphore is cleared, all waiting threads become eligi¬ 
ble to run; however, if the semaphore is reset before a given thread actually 
has a chance to run, this thread will again block (like DosSemRequest, the 
release of threads waiting for DosSemWait is level-triggered). 

DosSemWait allows several threads to wait for a single semaphore; alter¬ 
natively, the DosMuxSemWait function allows a single thread to wait for 
several semaphores. You pass DosMuxSemWait a list of semaphores; this 
function blocks the calling thread, if necessary, until one or more of the 
semaphores in the list is cleared. Note that unlike the other semaphore func¬ 
tions, the release of threads by DosMuxSemWait is edge-triggered, meaning 
that once a specified semaphore is cleared, the waiting thread will be 
released even if the semaphore is reset before the thread is actually sched¬ 
uled to run. 

When a process has completed using a system semaphore, it should relin¬ 
quish its access to the semaphore by calling DosCloseSem, passing this 
function the semaphore handle. The system deletes the semaphore when all 
open handles to the semaphore have been closed. Note that you do not call 
DosCloseSem for RAM semaphores. 

OS/2 provides several other semaphore options not discussed in this sec¬ 
tion, such as exclusively owned semaphores and counting semaphores. Also 
not discussed is the use of the timeout parameter to specify a finite time 
limit when waiting for a semaphore. This section only introduces the topic 
of using semaphores under OS/2, which can become quite complex. 


An Example Program 

The programs in Figures 7.1 and 7.2 demonstrate the following basic 
operations: 

♦ Executing a child process (the program in Figure 7.1 executes the 
program in Figure 7.2 as a child process) 

♦ Setting up a named shared memory segment that can be accessed 
by both the parent and child processes 

♦ Serializing access to the shared memory segment using a system 
semaphore 
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Figure 7.1 

This program demonstrates using a named shared memory segment and 
protecting access to this segment with a system semaphore. You can 
prepare the program using the following command line; 

cl /G2 /Zp /Lp fig7_l.c 

Note that the program FIG7_2.EXE is executed as a child process. 

*/ 

#define INCL_DOS 
#define INCL_SUB 
#include <os2.h> 

#include <stdio.h> 

#include <dos.h> 

#include <string.h> 

#include <process.h> 


char Arguments [] = 


/* Argument string passed to FIG7_2.EXE */ 
"FIG7_2.EXE\0\\SHAREMEM\\COMMON.DAT \\SEM\\COMMON.LCK"; 


void main () 

{ 

unsigned Error; 
unsigned short Selector; 
unsigned long far *ShareMemPtr; 
void far *SemHandle; 
char ObjectName [13]; 
RESULTCODES ExecResult; 
RESULTCODES WaitResult; 
int Go; 

unsigned Row, Col; 
char Buf [10 ]; 
unsigned ProcessID; 


/* For saving API error codes. 

/* Selector for shared segment. 
/* C pointer for shared segment. 
/* System semaphore handle. 

/* Used by DosExecPgm. 

/* Used by DosExecPgm. 

/* Used by DosCWait. 

/* Flag to stop loop. 

/* Screen positions. 

/* For formatting screen output. 
/* Used by DosCWait. 


/*** Allocate a named, shared segment. **************************************/ 
Error = DosAllocShrSeg 

(4, /* Number of bytes in segment. */ 

" \\SHAREMEMWC0MM0N.DAT", /* Name of shared segment. */ 

^Selector); /* Variable to receive selector. */ 

if (Error) 

fprintf (stderr,"Error %d calling DosAllocShrSeg\n M , 

Error); 

exit (1); 

} 

FP_SEG (ShareMemPtr) = Selector; 

FP_OFF (ShareMemPtr) = 0; 

*ShareMemPtr = 0; 

/*** Create a system semaphore. *********************************************/ 
Error = DosCreateSem 

(1, /* Indicates non-exclusive ownership. */ 

StSemHandle, /* Variable to receive handle. */ 

M \\SEM\\COMMON.LCK"); /* Name of semaphore. */ 

if (Error) 

fprintf (stderr,"Error %d calling DosCreateSem\n",Error); 
exit (1); 

} 


FIGURE 7.1: A program that allocates a named shared memory segment and uses a system semaphore 
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/*** Clear the screen and display a box. ************************************/ 
VioScrollnn /n.n.flvffff rivffff fiv-f-f-f-f h \ .1 a \ . ' 


-UUU Q WJk. •- 

VioScrollDn (0,0,Oxffff,Oxffff,Oxffff," \x7 ' 
Row = 10? Col =25; 

VioWrtCharStr 
VioWrtCharStr 
VioWrtCharStr 
VioWrtCharStr 
VioWrtCharStr 
VioWrtCharStr (" 


/ 0 ); 



", 30,Row++,Col,0) 
",30,Row++,Col,0) 
",30,Row++,Col,0) 
,30,Row++,Col,0) 
",30,Row++,Col,0) 
", 30,Row++,Col,0) 


/*** Execute an asynchronous child process. *********************************/ 
Error = DosExecPgm (ObjectName,sizeof (ObjectName),2,Arguments,0, 
&ExecResult,"FIG7 2.EXE"); 

if (Error) 

{ 

fprintf (stderr,"Error %d calling DosExecPgm; ObjectName = %s\n", 
Error,ObjectName); 

exit (1); 

> 


/*** Access the shared memory segment. **************************************/ 
Go = 1; ' 

while (Go) 

{ 

DosSemRequest 

(SemHandle, /* Semaphore handle. */ 

_1L )/ /* Timeout value => wait indefinitely. */ 

if (*ShareMemPtr < 10000L) 

++*ShareMemPtr; 

else 

Go = 0; 

DosSemClear (SemHandle); 

} 


/*** Print the final value of the data item in the shared segment. **********/ 
sprintf (Buf,"%lu",*ShareMemPtr); 

VioWrtCharStr (Buf,strlen (Buf),Row-4,Col+20,0); 

/*** Wait for child process to end, then free the shared memory & semaphore.*/ 
DosCWait (1,0,&WaitResult,&ProcessID,ExecResult.codeTerminate); 

DosFreeSeg (Selector); 

DosCloseSem (SemHandle); 

} /* end main */ 


FIGURE 7.1: A program that allocates a named shared memory segment and uses a system semaphore 
(continued) 


/* 

Figure 7.2 

This program is executed as a child process by the program FIG7_1.EXE. 
You can prepare this program using the following command lines 

cl /G2 /Zp /Lp fig7 2.c 

*/ 

#define INCL DOS 


FIGURE 72: A program that is executed as a child process by the program in Figure 7 .1 
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#define INCL_SUB 
#include <os2.h> 

#include <stdio.h> 

#include <process.h> 

#include <dos.h> 

#include <string.h> 

void main (int argc, char *argv []) 

unsigned Error; /* For saving API error codes. */ 

unsigned short Selector; /* Selector for shared segment. */ 

void far *SemHandle; /* System semaphore handle. */ 

unsigned long far *ShareMemPtr; /* C pointer for shared segment. / 

char Buf [101; /* For formatting screen output. */ 

int Go; /* Flag to stop loop. */ 

/*** Obtain access to shared memory allocated by parent process (FIG7_1.EXE)*/ 

Error = DosGetShrSeg , . , 

(argv [1], /* Global name of shared segment. / 

Selector); /* Variable to receive selector. */ 

if (Error) 

fprintf (stderr,"Error %d calling DosGetShrSeg\n",Error); 
exit (1); 

FP_SEG (ShareMemPtr) = Selector; 

FP_0FF (ShareMemPtr) = 0; 

/*** Open the semaphore created by parent process (FIG7_1.EXE). */ 

Error = DosOpenSem . . . ,, */ 

(&SemHandle, /* Variable to receive semaphore handle. / 

argv [2]); /* Global name of semaphore. */ 

if (Error) 

fprintf (stderr,"Error %d calling DosOpenSem\n",Error); 
exit (1); 

> 

/*** Access the shared memory segment. **************************************/ 
Go = 1; 
while (Go) 

{ 

DosSemRequest , 

(SemHandle, /* Semaphore handle. / 

_1 L ). /* Timeout value => wait indefinitely. */ 

if (*ShareMemPtr < 10000L) 

++*ShareMemPtr; 

else 

Go = 0; 

DosSemClear (SemHandle); 

> 

/*** print the final value of the data item in the shared segment. **********/ 
sprintf (Buf,"%lu",*ShareMemPtr); 

VioWrtCharStr (Buf,strlen (Buf),12 f 45,0); 

y*** Relinquish access to the shared segment and semaphore. */ 

DosFreeSeg (Selector); 

DosCloseSem (SemHandle); 

} /* end main */ 


FIGURE 7.2: A program that is executed as a child process by the program in Figure 7.1 (continued) 
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The main function of Figure 7.1 first calls DosAllocShrSeg to allocate a 
named shared memory segment. The full name of the segment is \SHARE- 
MEM\COMMON. DAT, and its length is 4 bytes (to accommodate a single 
variable of C, type long). DosAllocShrSeg returns a selector to the shared seg¬ 
ment, which is assigned to the pointer ShareMemPtr (of type unsigned long 
far *). ShareMemPtr is then used to initialize the shared data item to 0. 

Next, main calls DosCreateSem to create a system semaphore. The 
semaphore is set up so that the owning process does not have exclusive 
access (by setting the first parameter to 1; both processes must be able to 
freely set and clear the semaphore). The semaphore is given the name 
\SEM\COMMON. LCK. 

The program clears the screen and draws a box, which will be used later 
to display the final value of the shared data. The program now executes 
FIG7_2.EXE as a child process; the parameters are the same as those used 
to execute the child process in the example program of Figure 6.5, except 
for the program name (parameter 7), and the argument pointer (parameter 
4). This program uses the argument pointer to pass the child process a com¬ 
mand line, which contains the name of the child process (zero-terminated 
and accessed by the child through argv [0]), the name of the shared memory 
segment (blank-terminated and accessed through argv [1]), and the name 
of the system semaphore (zero-terminated and accessed through rgv [2]). 

After DosExecPgm returns, the main function runs asynchronously 
with the child process, and it enters a loop that accesses the data in the 
shared segment. This loop simply increments the value of the shared data 
item until the result is greater than or equal to 10,000. Note that the child 
process contains the same loop; thus, the two processes simultaneously read 
and update the shared data segment, sharing the task of incrementing the 
variable it contains. 

The portion of the program that tests the value of the shared variable, 
and then increments this variable if it is within range, is a critical section of 
code, since it must be executed by only one process at a time. This section 
of code is therefore protected in both processes by surrounding it with calls 
to DosSemRequest and DosSemClear. Consider the following scenario that 
could occur if access to this section were not serialized: The first process 
tests the variable and finds that it equals 9,999; before this process can 
increment the variable, however, it is preempted and the second process 
gains control. The second process also finds the value to be 9,999 and there¬ 
fore increments it; when the first process again receives control it also incre¬ 
ments the variable, since it has already performed its test. The result is that 
the final value is 10,001 rather than 10,000, and the program has failed. 
Although this may seem a small window of possibility, the art of writing a 
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reliable multitasking program demands that all such windows be identified 
and eliminated. 

The program in Figure 7.2, which is executed as a child process, first 
obtains access to the shared memory segment by calling DosGetShrSeg, 
passing the name of the segment that it receives as the first argument from 
the parent process (argv [1]), and obtaining a valid selector to the shared 
segment. (Note that the parent process does not simply pass the address of 
the shared segment to the child, since the selector portion of this address is 
valid solely within the parent process. Only the name of the segment 
is global; each process must obtain its own selector.) 

The child process likewise calls DosOpenSem to obtain its own valid 
handle to the system semaphore that was created by the parent process. The 
child passes this function the semaphore name received from the parent 
through argv [2], The child process then enters a program loop that 
accesses the shared data (identical to the loop in the parent process). 

Once the routine for accessing the shared memory is completed, both the 
parent and child processes print the final value of the common variable 
within the box that was displayed earlier by the parent. Both processes also 
relinquish their access to the shared memory segment (by calling DosFreeSeg) 
and the system semaphore (by calling DosCloseSem). Before closing these 
resources, however, the parent process calls DosCWait to make sure the 
child process has completed (this step is taken because the parent process 
may have reached this point in the code before the child process has 
obtained access to both the shared memory segment and the system 
semaphore). 


USING PIPES 


A pipe is a mechanism that allows two processes to directly exchange a 
stream of data using the standard OS/2 file 1/O functions. Typically, a par¬ 
ent process creates a pipe to communicate with a child process; alterna¬ 
tively, a parent can set up a pipe to allow one child process to communicate 
with another child. By using file redirection (as explained in this section) all 
I/O performed by a child process through standard input and output can be 
transparently rerouted to or from another process; thus, a program run as a 
child process does not have to be written explicitly to use pipes. Note that 
pipes are the mechanism employed by the command interpreter to reroute 
program I/O in response to the | command line operator. Also, the pipes 
discussed in this section are known as anonymous pipes to distinguish them 
from named pipes, which are not supported by OS/2 version 1.0 but will be 
available in future versions. 
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Table 7.3 summarizes the OS/2 functions for managing pipes. Note that 
all of the functions in this table except DosMakePipe also provide general- 
purpose file-handling services, and are used to manage pipe I/O in the same 
manner that they are used for managing I/O to disk files or character 
devices. 

The first step toward establishing interprocess communication through a 
pipe is to create the pipe using the function DosMakePipe. You must pass 


Function 

Purpose 

▼ 

DosClose 

Closes a pipe; you pass this function the pipe handle. 

DosDupHandle 

Returns a file handle that refers to the same file as a 
specified handle; you pass an open file handle and the 
function returns a new handle referring to the same 
file. Also, you can force a specified handle to refer to 
the same file as another specified handle; in this case, 
you pass both file handles. 

DosMakePipe 

Creates a new pipe. You pass this function the desired 
pipe size and it returns a read handle and a write 
handle for performing I/O to the pipe. 

DosQHandType 

Returns a code indicating whether a given handle 
refers to a disk file, a device, or a pipe. You pass this 
function the handle in question. 

OosRead 

Reads from a pipe. You pass the pipe handle, the 
address of the receiving buffer, and the length of this 
buffer (which equals the number of bytes that will be 
read, if possible); DosRead returns the number of 
bytes actually read. 

Dos Write 

Writes a specified number of bytes to a pipe. You pass 
the pipe handle, the address of the buffer containing 
the data to be written, and the length of this buffer 
(which equals the number of bytes that will be 
written, if possible); Dos Write returns the number of 
bytes actually written. 


TABLE 7.3: OS/2 Functions for Managing Pipes 
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this function the desired size of the pipe in bytes (a value from 1 to 64 kilo¬ 
bytes; if the size parameter is 0, DosMakePipe will use a default size). Dos- 
MakePipe returns both a read handle and a write handle (unlike the 
DosOpen function, which opens or creates a disk file or device and returns a 
single handle for both reading and writing). 

Once the pipe has been created, one process typically writes to the pipe 
and another process reads from the pipe. The writing process calls 
DosWrite, passing this function the write handle returned by DosMake¬ 
Pipe, and the reading process calls DosRead, specifying the read handle. If 
there is insufficient room in the pipe to accommodate a requested write 
operation, DosWrite blocks until the reading process has removed sufficient 
data to provide space. Likewise, DosRead blocks the requesting thread 
until sufficient data has been written to the pipe to fulfill the read request. 
Note, however, that when the last write handle for the pipe is closed (using 
DosClose, described below), DosRead returns control to the calling thread 
and reports that 0 bytes have been read. (In this case, no error code is 
returned; reporting that 0 bytes have been read is the standard method 
DosRead uses to report that the end of the file has been reached.) 

Data written to a pipe is removed by a read operation, one character at a 
time and in the same order that it was written (a pipe is thus a first-in, first- 
out data structure). Pipe I/O is much like that to a character device; data is 
transferred as a sequential stream of characters, and random access is not 
possible. Thus, you cannot call DosChgFilePtr to seek a specific character 
position within a pipe. A process, however, may determine whether a par¬ 
ticular handle is associated with a disk file or is connected with a pipe or 
character device by calling the function DosQHandType. 

When a process finishes using a pipe, it should call DosClose to relin¬ 
quish its ownership of the pipe handle. The system releases the pipe when 
the last handle has been closed. 

The read and write handles returned by DosMakePipe are valid only 
within the calling process, or within a child process that inherits these han¬ 
dles. Thus, pipes can be used for communication solely among related pro¬ 
cesses. Note that an arbitrary process cannot simply call DosOpen to obtain 
a handle to a pipe created by another process, because the pipes discussed in 
this section are anonymous (that is, they are not identified by name, and 
DosOpen must be passed a name). The named pipes, however, which will be 
supported in future versions of OS/2, can be accessed by any process that 
knows the global name used to identify a given pipe; named pipes are thus 
similar to named shared memory, system semaphores, and queues, which 
are likewise identified by global names. (It will even be possible to access a 
named pipe created on another machine connected to a network!) 
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The program in Figure 7.3 shows how to use the pipe mechanism to 
establish direct communication between two child processes that perform 
1/O through the standard input and standard output file handles. This pro¬ 
gram runs CMD.EXE (which performs a DIR command) and the OS/2 
SORT.EXE utility as child processes. The parent process sets up a pipe so 
that the output from the DIR command is sent directly to the SORT utility; 
the result is a sorted directory listing. Note that this program has the same 
result as issuing the following OS/2 command at the operating-system 
prompt: 

DIR | SORT 

The program first calls DosMakePipe to create an 8-kilobyte pipe, and 
saves the read and write handles. Before running the directory command 
and sort program as child processes, the parent process must correctly redi¬ 
rect the standard I/O handles so that the child processes will communicate 
through the pipe. The example program uses the following sequence of 
steps to perform this redirection: 

1. DosDupHandle is called to duplicate the existing standard output 
handle so that this handle can be restored after it has been redi¬ 
rected (the duplicate handle is saved in SaveHandle; see the 
description of DosDupHandle in the section entitled Using Multi¬ 
ple Processes in Chapter 6). 

2. DosDupHandle is called again to redirect the standard output 
handle to the write handle for the pipe. 


/* 

Figure 7.3 

This example program shows how to establish communication between 
two child processes using pipes. You can prepare this program 
using the following command line; 

cl /G2 /Zp /Lp fig7 3.c 

*/ 

Idefine INCL_DOS 
iinclude <os2.h> 

#include <stdio.h> 

#include <process.h> 

char Arguments [] = "CMD.EXE\0/cDIR"; /* Argument string passed to CMD.EXE*/ 


FIGURE 7.3: A program that establishes communication between two child processes using pipes 
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void main () 

{ 

unsigned Error; 
unsigned short ReadHandle; 
unsigned short WriteHandle; 
unsigned short SaveHandle; 
unsigned short Stdln = 0; 
unsigned short StdOut = 1; 
char ObjectName [13]; 
RESULTCODES Result; 




/* For saving API error codes. */ 

/* Handle to read from pipe. */ 

/* Handle to write to pipe. */ 

/* Saves standard input/output handles. */ 

/* Standard input handle. */ 

/* Standard output handle. */ 

/* Used by DosExecPgm. */ 

/* Used by DosExecPgm. */ 

***********************************/ 

*/ 
*/ 
*/ 


/*** Create a pipe. 

Error = DosMakePipe 

(&ReadHandle, /* Variable to receive read handle. 

&WriteHandle, /* Variable to receive write handle. 

8192); /* Size of pipe = 8 kilobytes, 

if (Error) 

fprintf (stderr,"Error %d calling DosMakePipe\n",Error); 
exit (1); 

> 

/*** Save old standard output handle and redirect it to point to the pipe. **/ 
SaveHandle = Oxffff; 

DosDupHandle (StdOut, &SaveHandle); 

DosDupHandle (WriteHandle,&StdOut); 

/*** Execute CMD.EXE as a child process. ************************************ I 
Error = DosExecPgm (ObjectName,sizeof (ObjectName), 2, Arguments , 0 , 

SeResult, "CMD.EXE") ; 

if (Error) 

fprintf (stderr,"Error %d calling DosExecPgm; ObjectName = %s\n", 
Error,ObjectName); 

exit (1); 

> 

/*** Restore standard output; then save and redirect standard input. *******/ 
DosDupHandle (SaveHandle,&StdOut); 

DosDupHandle (Stdln,&SaveHandle); 

DosDupHandle (ReadHandle,&StdIn); 

j-k-k-k close pipe write handle to prevent S0RT.EXE from hanging. **************/ 
DosClose (WriteHandle); 

/*** Execute SORT.EXE as a child process. ***********************************/ 
Error = DosExecPgm (ObjectName,sizeof (ObjectName),2,0,0,&Result, 

"SORT.EXE"); 

if (Error) 

fprintf (stderr,"Error %d executing SORT.EXE\n", Error); 
exit (1); 

j-k-kk Restore standard input handle and close unneeded handles. **************/ 
DosDupHandle (SaveHandle,&StdIn); 

DosClose (SaveHandle); 

DosClose (ReadHandle); 


/kkk At this point, the program could perform other tasks and would have the 
use of its original standard input and output handles. ***************** 

} /* end main */ 


/ 


FIGURE 7.3: A program that establishes communication between two child processes using pipes 
(continued) 
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3. CMD.EXE is run as a child process and is passed the DIR com¬ 
mand. The standard output handle inherited by CMD.EXE points 
to the pipe so that the directory listing enters the pipe rather than 
being displayed on the screen. 

4. When control returns from DosExecPgm, the redirected standard 
output handle has already been inherited by the child process; 
therefore, the original target for this handle can be restored from 
SaveHandle by calling DosDupHandle again. 

5. The standard input handle is now duplicated in SaveHandle. 

6. The standard input handle is redirected to the read handle for the 
pipe. 

7. Before SORT.EXE is run as a child process, the pipe write handle 
(WriteHandle) is closed by calling DosClose. If this handle were 
not closed, then both the parent process as well as SORT.EXE (by 
inheritance) would hold open write handles to the pipe. However, 
as long as any process holds an open write handle to the pipe, 
DosRead will not return an end-of-file indication, even after the 
CMD.EXE child process has terminated (end-of-file is indicated 
when DosRead returns control but reports that 0 bytes have been 
read). Therefore, the call to DosRead from SORT.EXE would 
never return, suspending this program indefinitely. 

8. DosExecPgm is now called to execute SORT.EXE as a child pro¬ 
cess; SORT inherits the redirected standard input handle and 
therefore receives its input from the pipe. 

9. Upon return from DosExecPgm, CMD.EXE (which performs a 
directory listing), SORT.EXE, and the parent process all run con¬ 
currently, and the output from CMD.EXE goes through the pipe 
and becomes the input for SORT.EXE. 

10. The parent process now makes its final call to DosDupHandle to 
restore the standard input handle, and closes two handles that are 
no longer needed: SaveHandle and ReadHandie. 

11. At this point, the parent process could perform other tasks while 
the sort operation continues in the background, and the standard 
input and output handles would have the same meanings they had 
when the parent began executing. 

Note that you can use methods similar to those employed by the example 
program to establish communication between a parent and a child process. 
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See also Figure 6.5 and the section in Chapter 6 entitled Using Multiple 
Processes. 


OS/2 queues allow you to exchange discrete, variable-length packets of data 
between threads or processes. Unlike pipes, data exchanged through queues is 
contained in shared memory and therefore does not have to be copied; accord¬ 
ingly, queues provide an efficient means for transferring data. 

A queue is composed of elements (or messages)-, each element contains 
the memory address and size of a variable-length body of data, plus the ID 
of the sending process and an event code (explained below). These elements 
are ordered according to their relative times of insertion—either first-in, 
first-out (FIFO) or last-in, first-out (LIFO)—or by their priorities. The pro¬ 
cess that creates a queue is known as the owner or server, a queue is identi¬ 
fied by a global name, and any other process that knows this name can 
obtain access to the queue. Only the owner, however, can examine or extract 
elements from the queue; any other process that has an open handle can add 
new elements. 

Table 7.4 summarizes the OS/2 functions for managing queues. The first 
step is to create the queue by calling DosCreateQueue. You must pass a code 
(in the second parameter) for the type of ordering that is to be used for the 
queue elements: either FIFO, LIFO, or by priority. You must also specify 
(through the third parameter) the name used to identify the queue. This 
name must follow OS/2 file-naming conventions and begin with 
\QUEUES\ (thus, just like shared memory segments and system sema¬ 
phores, queues are kept in fictitious “directories” located in RAM). 
DosCreateQueue returns a handle that can be used for subsequent queue 
function calls by any thread within the current process. 

Once a queue has been created, any other process that knows its global 
name (either in advance or at run-time through some other form of 
interprocess communication) can obtain a handle by calling DosOpen- 
Queue. You pass this function the name of the queue (the third parameter), 
and the function returns a valid handle as well as the ID of the process that 
owns the queue (an important use for the owner ID is illustrated by the pro¬ 
gram of Figure 7.5, described later in this section). 

Any process that holds a valid handle can add elements to the queue by 
calling DosWriteQueue. The first parameter you pass to this function is the 
queue handle; the third and fourth parameters give the address and length 
of the queue data. Note that this data must be in a segment accessible to the 
owner of the queue (the owner is always the recipient of the data and reads 
the data directly from the address you supply). Therefore, if the queue is 
not owned by the current process, the data must be located within a shared 
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Function 

Purpose 

V 

DosCloseQueue 

Closes the specified queue; you pass this 
function the queue handle returned by 
DosCreateQueue or DosOpenQueue. 

DosCreateQueue 

Creates and opens a queue that is owned by the 
calling process. You pass the name to be 
assigned to the queue and the desired ordering 
method; DosCreateQueue returns the queue 
handle. 

DosOpenQueue 

Makes a queue created by another process 
available to the current process. You pass the 
name of the queue; the function returns a 
handle valid within the calling process and the 

PID of the owner of the queue. 

DosPeekQueue 

Retrieves an element from a queue without 
removing it. You pass the queue handle, a code 
for the desired element, a code indicating 
whether to wait if no elements are currently in 
the queue, and the handle of a semaphore to be 
cleared when the queue contains data (used 
only if the function does not wait for data). 
DosPeekQueue returns the address and length 
of the queue element, the PID of the sending 
process, an “event code” from the sending 
process, and the ID and priority of the element 
peeked. Only the owning process may issue this 
function call. 

DosPurgeQueue 

Removes all elements contained in a queue. 

You pass the handle of the queue; only the 
owning process can issue this function call. 

DosQueryQueue 

Reports the number of elements in a queue. 

You pass the queue handle and the function 
returns the number of elements. 

DosReadQueue 

Reads and removes a queue element. You pass 
the queue handle, a code for the desired 
element, a code indicating whether to wait if no 
elements are currently in the queue, and the 


TABLE 7.4: OS/2 Functions for Managing Queues 
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Function 

V 

Purpose 

V 

DosReadQueue (cont.) 

handle of a semaphore to be cleared when the 
queue contains data (used only if the function 
does not wait for data). DosReadQueue 
returns the address and length of the queue 
element, the PID of the sending process, an 
“event code” from the sending process, and the 

ID and priority of the element read. Only the 
owning process can issue this function call. 

DosWriteQueue 

Adds an element to a queue. You pass the 
queue handle, an “event code” that has 
meaning to the receiving process, the address 
and length of the queue element, and a priority 
value for priority-based queues only. 


TABLE 7.4: OS/2 Functions for Managing Queues (continued) 


memory segment. Also, the data address that you pass must be valid within 
the owning process . The example programs of Figures 7.4 and 7.5 show 
how to use giveaway shared memory segments to contain the data associ¬ 
ated with queue elements. 

The second parameter to DosWriteQueue is an event code ; you can 
freely use this word to pass any type of information to the reader of the 
queue. (The programs in Figures 7.4 and 7.5 use this field as a code to indi¬ 
cate whether the current queue element is the last element added by the 
sending process.) Note that one or more processes may add multiple ele¬ 
ments to the queue; these elements are stored until they are extracted by the 
owner. AJthough messages from several processes may be intertwined in the 
queue, the owning process can determine the source of any queue element, 
since the ID of the sending process is stored within the element. 

Once the owning process has created a queue, it may call either DosPeek- 
Queue or DosReadQueue to read the elements that have been written to the 
queue. DosPeekQueue allows the owning process to read queue elements 
without removing them. You must pass this function (as the first parameter) 
the handle that was obtained from the call to DosCreateQueue, and a code 
(the sixth parameter) indicating whether the calling thread should be 
blocked, if necessary, until an element is available. If you choose to have the 
function return immediately—whether or not an element is available—then 
you can pass the address of a semaphore (the eighth parameter) that the sys¬ 
tem will clear as soon as an element has been added. 
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DosPeekQueue also accepts an element code (the fifth parameter); if this 
code is set to 0, then the first queue element is returned (according to the 
queue-ordering scheme that was specified when the queue was created.) 
When DosPeekQueue returns, it sets this parameter to the number of the 
queue element that was actually read. If, however, the element code is set to a 
nonzero value upon calling DosPeekQueue, then the function will obtain the 
queue element that follows the indicated element . Thus, if you assign the ele¬ 
ment code a value of 0 for the first call to DosPeekQueue, you can then call this 
function repeatedly—without altering the element code between calls—to read 
through the queue in order, beginning with the first element. 

In addition to the element code, DosPeekQueue returns the address and 
length of the queue data, the ID of the sending process, and the event code 
that was passed to DosWriteQueue by the sending process. If the queue is 
ordered by priority, DosPeekQueue also returns the priority of the element 
that was read. 

The DosReadQueue function has the same parameters as DosPeek¬ 
Queue and works in the same manner as this function, with two important 
differences. First, DosReadQueue removes the element it reads from the 
queue, whereas DosPeekQueue leaves the element in the queue. Second, 
DosReadQueue reads the same element that is specified by the element code 
(the fifth parameter), whereas DosPeekQueue reads the following element. 
As described above, you can use DosPeekQueue to examine the queue ele¬ 
ments in order. If you find an element that you would like to remove from 
the queue, you can then pass the element code returned by DosPeekQueue 
to DosReadQueue, which will cause this element to be extracted from 
the queue. 

The process that owns a queue can remove all elements that it contains 
by calling DosPurgeQueue. Also, any process that owns a queue handle can 
determine the number of elements contained in this queue by calling Dos- 
QueryQueue. Finally, when a process has completed using a queue, it 
should call DosCloseQueue. A process that does not own the queue simply 
relinquishes its access to the queue by calling this function. When the own¬ 
ing process calls DosCloseQueue, however, the queue is actually deleted; if 
another process subsequently attempts to write to the queue, DosWrite¬ 
Queue returns an error message indicating that the queue does not exist. 

An Example Program 

The programs listed in Figures 7.4 and 7.5 show how to send data from one 
process to another using queues. These programs also illustrate the use of 
giveaway shared memory segments, described at the beginning of the 
chapter. 
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/* 

Figure 7.4 

This program demonstrates using giveaway shared memory segments and an 
OS/2 queue to communicate between two processes. Note that FIG7_5.EXE 
is run as a child process. You can prepare this program using the 
following command line: 

cl /G2 /Zp /Lp fig7_4.c 

*/ 

#define INCL_DOS 
Idefine INCL_SUB 
tinclude <os2.h> 

#include <stdio.h> 
linclude <process.h> 

#include <dos.h> 


/* Argument string passed to FIG7_5.EXE. */ 
char Arguments [] = "FIG7_5.EXE\0\\QUEUES\\TEST.QUE"? 


/* For saving API error codes. */ 
/* Holds the queue handle. */ 
/* Used by DosExecPgm. */ 
/* Used by DosExecPgm. */ 
/* Used by DosReadQueue. */ 
/* DosReadQueue: length of element. */ 
/* DosReadQueue: address of element. */ 
/* DosReadQueue: priority of element. */ 


void main () 

{ 

unsigned Error? 
unsigned short QueueHandle; 
char ObjectName [13]? 

RESULTCODES Result? 
unsigned long Request? 
unsigned DataLength? 
unsigned long DataAddress? 
unsigned char ElemPriority? 

/*** Create the queue. ******************************************************/ 
Error = DosCreateQueue 

(&QueueHandle, /* Variable to receive queue handle. */ 

0, /* 0 indicates FIFO ordering. */ 

"\\QUEUES\\TEST.QUE")? /* Name to be assigned queue. */ 

if (Error) 

fprintf (stderr,"Error %d calling DosCreateQueue\n",Error)? 
exit (1)? 

> 


/*** Execute the child process, passing it the queue name as an argument. ***/ 
Error = DosExecPgm (ObjectName,sizeof (ObjectName),1,Arguments,0,SResult, 
"FIG7_5.EXE")? 

if (Error) 

{ 

fprintf (stderr,"Error %d calling DosExecPgm; ObjectName = %s\n", 
Error,ObjectName); 

exit (1); 

> 


/*** Read and display messages from queue until the event code is 0. ********/ 
do 

{ 

/* Extract the next queue element. */ 

DosReadQueue 

(QueueHandle, /* Queue handle for this process. */ 

5-Request, /* Receives sender PID and event code. */ 

ScDataLength, /* Receives length of queue data. */ 


FIGURE 7.4: A program that shows how to exchange data between processes using giveaway shared mem¬ 
ory segments and queues 
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SDataAddress, 
0 , 

0 , 

&ElemPriority, 
0L) ; 


/* Receives far address of queue data. 

/* Element code indicates first element. 
/* Wait for element. 

/* Receives priority (not used here). 

/* Semaphore handle (not used here). 


/* Display the queue element. 

VioWrtTTy ((char far *)DataAddress,DataLength,0); 


/* Free the giveaway shared memory segment. */ 

DosFreeSeg (FP_SEG (DataAddress)); 

> 

while (Request & OxffffOOOOL); /* Event code is high-order word. */ 

/*** close the queue. *******************************************************/ 
DosCloseQueue (QueueHandle); 


> /* end main */ 


FIGURE 7.4: A program that shows how to exchange data between processes using giveaway shared mem¬ 
ory segments and queues (continued) 


The program in Figure 7.4 first calls DosCreateQueue to create a queue. The 
specified order is first-in, first-out (requested by the 0 value passed as the second 
parameter), and the name of the queue is \QUEUES\TESTQUE. The queue 
handle is saved in the variable QueueHandle. This program is thus the owner of 
the queue. 

Next, the program executes FIG7_5.EXE (prepared from the C file of Fig¬ 
ure 7.5) as a child process, passing the name of the queue as an argument. The 
parent program then enters a loop that uses DosReadQueue to remove the ele¬ 
ments from the queue written by the child process, until it encounters an ele¬ 
ment with an event code of 0. Event codes are placed in each queue element by 
the child process, and a value of 0 indicates that the last queue element has been 
sent. Note that the system copies the event code into the high-order word of the 
unsigned long Request variable (the address of this variable is passed as the 
second parameter to DosReadQueue). 

After displaying the contents of each queue message, the parent process 
frees the giveaway shared memory that contains the element by calling 
DosFreeSeg. Note that the buffer address that DosReadQueue copies into 
DataAddress is a far address (that is, containing both a segment and an 
offset); DosFreeSeg takes only the segment value, which is conveniently 
extracted using the predefined C macro FP_SEG. Finally, when the last ele¬ 
ment has been extracted from the queue, the program calls DosCloseQueue 
to remove the queue. 

The child process, listed in Figure 7.5, first obtains access to the queue by 
calling DosOpenQueue, passing the name of this queue that was received as 
an argument (argv [1]). The handle is stored in QueueHandle, and the ID 
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/* 

Figure 7.5 

This program is run as a child process by FIG7_4.EXE. The executable 
file can be prepared using the following command line? 

cl /G2 /Zp /Lp fig7_5.c 

*/ 

#define INCL_DOS 
#include} <os2.h> 

#include <stdio.h> 

#include <string.h> 
linclude <dos.h> 

#include <process.h> 

void FarCopy (unsigned DestSeg,unsigned DestOff,char *Source); 

char *MessageTable [] = /* Strings that will be written to the queue. 

{ 

"This is the first queue element from the child process\r\n", 

"This is the second queue element from the child process\r\n", 

"This is the third queue element from the child process\r\n", 

"This is the fourth queue element from the child process\r\n", 

0 

}; 


unsigned RequestTable [] = {1,1,1,0}; /* Event codings written to queue. * 

void main (int argc, char *argv []) 

{ 

unsigned Error; /* For saving API error codes. * 

unsigned OwnerPID; /* DosOpenQueue: ID of queue owner. * 

unsigned short QueueHandle; /* Holds the queue handle. * 

unsigned Size; /* Length of queue elements. * 

unsigned short Selector; /* Selector of giveaway shared segment. * 

unsigned short RecipientSelector; /* Selector valid for queue owner.* 

unsigned char far *RecipientAddress; /* Queue element address that * 

/* is valid for the owner. * 

int i; /* Loop index. * 

/*** Open the queue. ******************************************************** 
Error = DosOpenQueue 

(&OwnerPID, /* Receives PID of queue owner. * 

SQueueHandle, /* Reveives queue handle. * 


argv [1]); /* Global name of queue. * 

if (Error) 

{ 

fprintf (stderr,"Error %d calling DosOpenQueue\n",Error); 
exit (1); 

} 

/*** Add elements to the queue. ********************************************* 
for (i=0;MessageTable [i];++i) 

{ 

Size = strlen (MessageTable [i]) + 1; 

/* Allocate a giveaway shared memory segment for a queue element. * 
Error = DosAllocSeg 

(Size, /* Length of giveaway memory segment. * 

&Selector, /* Receives selector valid in this process. * 

1); /* Indicates segment is shareable w/ DosGiveSeg* 


/ 


/ 


/ 

/ 


FIGURE 7.5: A child process executed by the program of Figure 7.4 
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if (Error) 

{ 

fprintf (stderr,"Error %d calling DosAllocSeg\n"); 
exit (1); 

} 

/* Write a string to the segment. */ 

FarCopy (Selector,0,MessageTable [i]); 

/* Obtain a selector valid for the process that owns the queue. */ 
Error = DosGiveSeg 

(Selector, /* Selector for this process. */ 

OwnerPID, /* PID of segment recipient. */ 

&RecipientSelector); /* Selector valid for recipient. */ 

if (Error) 

{ 

fprintf (stderr,"Error %d calling DosGiveSeg\n"); 
exit (1); 

/* Once the segment is given away, access may be relinquished. */ 
DosFreeSeg (Selector); 


/* Add an element to the queue. 

FP_SEG (RecipientAddress) = RecipientSelector; 
FP_OFF (RecipientAddress) = 0; 

Error = DosWriteQueue 


Queue handle. */ 
Event code. */ 
Length of queue data. */ 
Far address of queue data for receiver*/ 
Priority (not used here). */ 


(QueueHandle, /* 

RequestTable [i], /* 

Size-1, /* 

RecipientAddres s, /* 

0 )? /* 

if (Error) 

{ 

fprintf (stderr,"Error %d calling DosWriteQueue\n") 
exit (1); 

} 

DosSleep (2000L); /* 2-second pause. 


} /* end for loop */ 


/*** Finally, close the queue. **********************************************/ 
DosCloseQueue (QueueHandle); 


} /* end main */ 


void FarCopy (unsigned DestSeg,unsigned DestOff,char *Source) 

/* 

This function copies the ’Source’ string to the far address that has 
segment 'DestSeg' and offset 'DestOff'. 

*/ 

{ 

char far *CharFP; 

FP_SEG (CharFP) = DestSeg; 

FP_OFF (CharFP) = DestOff; 
while (*CharFP++ = *Source++) 

f 

} /* end FarCopy */ 


FIGURE 7.5: A child process executed by the program of Figure 7.4 (continued) 
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USING SIGNALS 


of the owning process (which is also the parent) in OwnerPIB. The pro¬ 
gram then adds four elements to the queue; each element is written to the 
queue using the following sequence of steps: 

1. DosAllocSeg is called to allocate a giveaway shared memory seg¬ 
ment that is just large enough to contain the body of the queue 
message (see the section on giveaway shared memory near the 
beginning of the chapter). 

2. A message string, contained in one of the elements of the 
Mess&geTable array, is copied into the shared memory segment 
using the local FarCopy function. 

3. DosGiveSeg is called to obtain a selector for the shared memory 
segment that is valid within the process that owns the queue . 

4. Once the data have been written to the shared segment and the 
selector for the owning process has been obtained, DosFreeSeg is 
called to relinquish access to this segment (the segment is actually 
freed only after the parent process also calls DosFreeSeg). 

5. DosWriteQueue is called to add the new element to the queue. 

Note that a far address for the queue data, valid within the recipi¬ 
ent process, is constructed in the variable Recipient Address. The 
program also passes an event code (contained in RequestTable) to 
indicate whether the current queue element is the last one. 

6. To simulate an actual application, which might need to perform 
other tasks before sending the next message, DosSleep is called to 
create a two-second delay. 

Finally, before terminating, the child process relinquishes its access to the 
queue by calling DosCloseQueue. Note that rather than allocating entire 
segments for each queue element (an operation used by the example pro¬ 
gram that has high overhead), you could alternatively use the memory sub¬ 
allocation functions described in Chapter 8 (namely, DosSubAlloc, 
DosSubFree, and DosSubSet). 


OS/2 signals were introduced in Chapter 6 (in the section on Using Multiple 
Processes). The operating system sends a signal to a process in response to 
one of several events; when a signal occurs, the system interrupts the pro¬ 
cess and either performs a default action or passes control to a signal han¬ 
dler, if one has been installed. A variety of events can trigger a signal; each 
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event results in a different type of signal. Table 7.5 lists the different types of 
signals issued by OS/2; this table also gives the default actions that the sys¬ 
tem will take for each type of signal, and the codes used by the function 
DosSetSigHandler, explained later in this section. 

OS/2 allows you to install a signal-handling routine, which receives con¬ 
trol when a specific type of signal occurs, and which overrides the default 
action performed by the system. A signal handler always runs within the 
context of thread 1 (which is the first thread that receives control in a pro¬ 
cess). When a signal occurs, the system asynchronously interrupts thread 1 
(after this thread has completed its current instruction) and immediately 
passes control to the handler installed for this signal. If thread 1 is not cur¬ 
rently running, the signal handler does not receive control until thread 1 is 
next dispatched. The OS/2 signal mechanism is thus quite similar to hard¬ 
ware interrupts under MS-DOS, except that a signal is implemented entirely 


Event Causing 
Signal 

Explanation 

Code* 

Default System 
Action (No Handler 
installed) 

▼ 

▼ 

V 

V 

Control-C 

The user pressed Control-C 

1 

Terminates the process 

DosKillProcess 

Another process called 
DosKillProcess to terminate 
the current process 

3 

Terminates the process 

Control-Break 

The user pressed 

Control-Break 

4 

Terminates the process 

Signal A 

Another process called 
DosFlagProcess to send 
signal A to the current 
process 

5 

Ignores the signal 

Signal B 

Another process called 
DosFlagProcess to send 
signal B to the current 
process 

6 

Ignores the signal 

Signal C 

Another process called 
DosFlagProcess to send 
signal C to the current 
process 

7 

Ignores the signal 


* Code passed to DosSetSigHandler as parameter number 5 


TABLE 7.5: Types of Signals Generated by OS/2 
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in software, and only interrupts thread 1 of a process that has installed a 
handler for the specific event. 

What happens if thread 1 is currently executing an API function when 
the system needs to generate a signal? If the OS/2 function is one that will 
complete quickly, such as a disk file operation, then the thread is not inter¬ 
rupted until the function returns. If, however, the function is one likely to 
require a relatively long time, such as a device I/O operation or a call 
to DosSleep, then the system function is interrupted before completion. 

A Control-C or Control-Break signal handler receives control when the 
user presses the corresponding key combination. When the system detects 
one of these break keys, it passes control to the most recently installed sig¬ 
nal handler for the specific keystroke within the current screen group. If 
your program installs a break handler, then it can retain control if the user 
presses a break key, rather than allowing control to go to an ancestor pro¬ 
cess (such as CMD.EXE), which would most likely terminate your 
program. A typical action of a break-key signal handler within an interac¬ 
tive program would be to terminate the current program activity and return 
control to the main program menu or command processing loop. 

You can also install a signal handler that receives control when another 
application calls DosKillProcess to terminate the current process. Such a 
handler should not unduly delay process termination. Note also that neither 
a break-key signal handler nor a DosKillProcess signal handler is ideal for 
performing vital tasks that must be accomplished before process termina¬ 
tion, since these handlers are activated only under special termination con¬ 
ditions. Rather, you should perform important last-minute tasks from a 
function registered through DosExitList (mentioned in Chapter 6, under 
Using Multiple Threads); such a function is called regardless of how the 
program exits. 

Finally, you can install a signal handler that receives control when 
another process calls the OS/2 function DosFlagProcess to send the current 
process one of three general-purpose signals (identified as signals A, B, and 
C). This type of signal can be used as a unique form of interprocess com¬ 
munication, and is the primary topic of this section. Unlike other forms of 
interprocess communication, signals operate asynchronously with respect 
to the receiving process (other forms of interprocess communication 
demand that a process block or perform an explicit action to receive a mes¬ 
sage or exchange data with another process). Signals, however, as will be 
seen shortly, can convey only a small amount of information, and thus have 
limited usefulness for exchanging data. 

Table 7.6 summarizes the OS/2 functions for managing signals. The dis¬ 
cussion of these functions that follows emphasizes their use for interprocess 
communication. 
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Fyoctioo 

▼ 

Purpose 

▼ 

DosFlagProcess 

Sends one of three general-purpose signals (A, B , or 

C) to a process. You must pass this function the ID 
of the receiving process, a flag indicating whether the 
signal is to be sent to the process alone or to the 
process and all its descendants, a code for the specific 
signal, and an argument to be passed to the 
signal-handling routine. 

DosHoldSignal 

Temporarily suspends or resumes signal processing 
for the current process; you pass a flag indicating 
whether to suspend or resume. 

DosSetSigHandler 

Either installs or removes a handler for a given signal, 
causes the system to ignore a signal, disallows other 
processes from sending signals, or reactivates the 
signal-handling mechanism (which is temporarily 
suspended when a signal handler receives control). 

You pass a code for the desired action, and if 
necessary the address of the signal handler and the 
number of the signal. DosSetSigHandler returns the 
address of the previously installed signal handler and 
its action code. 


TABLE 7.6: OS/2 Functions for Managing Signals 


DosSetSigHandler is a broad-purpose function that allows you to install 
a handler for a specific type of signal, or to modify the OS/2 signal¬ 
handling mechanism in one of several other ways. When you call this func¬ 
tion, you must pass a code indicating the desired action (as the fourth 
parameter). The following are the specific actions you can perform using 
DosSetSigHandler (together with the corresponding action codes): 

♦ Install a handler for a specified signal (code 2) 

♦ Force the system to use its default action for the specified signal, 
effectively removing any handler previously installed for this signal 
(code 0) 

♦ Block all signals sent to the process via DosFlagProcess (code 3) 

$ Reset a signal (code 4) 

♦ Cause the system to ignore a specified signal (code 1) 
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To perform any of these actions, you must also pass DosSetSigHandler a 
code for the specific signal (as the fifth parameter); these codes are listed in 
Table 7.5. 

When using DosSetSigHandler to install a signal handler, you must pass 
the far address of this handler (as the first parameter). Subsequently, when¬ 
ever the specified signal occurs, thread 1 will be interrupted and the handler 
will receive immediate control. When the signal handler is installed to 
receive one of the three general signals (A, B, or Q sent by other processes, 
the operating system passes the handler two word-length parameters, the 
argument that the initiating process specified in the call to DosFlagProcess, and 
the number of the signal itself (the numbers are the same as the codes listed in 
Figure 7.5). The program in Figure 7.6, described later in this section, shows 
how to implement a signal-handling function in C. 

Note that when a handler for a specific signal receives control, all further 
attempts to generate the same signal are blocked until the signal handler 
calls DosSetSigHandler to reset the signal (action code 4; note the similarity 
between this mechanism and the reenabling of hardware interrupts under 
MS-DOS). A function that is nonreentrant should not reset the signal until 
the end of the function, to prevent recursive entries into the code. If the 
function issues a far return instruction, control passes back to the next 
instruction within the thread that was interrupted when the signal occurred. 
A signal handler, however, is not required to return; it may, for example, 
terminate the current process (through DosExit), or clean up the stack and 
jump to some other point in the program (in C, this can be performed using 
the setjmp and longjmp library routines). 

Note that when you install a signal handler, two problems can occur 
within thread 1. First, if this thread calls system functions, these function 
calls may be interrupted, possibly corrupting data (this is especially likely 
when performing character device I/O). Second, if thread 1 is interrupted 
when it is executing a critical section of code protected with a semaphore, 
deadlock can result. (Specifically, deadlock can occur if the signal handler 
never returns, leaving the semaphore permanently held by thread 1. Also, 
deadlock can result if the signal handler—or a subroutine that it calls— 
waits for the same semaphore that is held by thread 1.) To avoid these prob¬ 
lems, you can make sure that the code executed by thread 1 contains neither 
system calls nor critical sections protected with semaphores. Ideally, thread 
1 would be dedicated to receiving signals; while such a thread waits for a sig¬ 
nal, it should remain blocked (for example, by repeatedly calling DosSleep 
or blocking on a private semaphore that is never cleared.) 

Another method for avoiding problems is to call DosHoldSignal to tem¬ 
porarily suspend signal processing for the current process during a section 
of code in thread 1 that should not be interrupted. You pass this function a 
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flag indicating whether signals are to be disabled or reenabled (this is the 
only parameter). The following is an example: 

DosHoldSignal (1); /* Disables signals. */ 

/* Section of code that should not be interrupted by */ 
/* a signal. For example, this code may contain */ 
/* time-sensitive system calls, or hold a semaphore. */ 
DosHoldSignal (0); /* Reenables signals. */ 

Note that signals should remain disabled for a minimum amount of time 
Gust as hardware interrupts should be disabled for the minimum time). 
Also, the system maintains a count of the number of times DosHoldSignal 
is called to disable or enable a signal; accordingly, several requests to disable 
a signal must be followed by an equal number of requests to enable the sig¬ 
nal before the signal is actually reenabled. 

A process can send one of the three general-purpose signals to another 
process by calling DosFlagProcess. Note that the sending process must 
know the ID of the receiving process. Also, this function allows you to spec¬ 
ify a one-word parameter to be passed to the receiving process. When a sig¬ 
nal is generated, the only information received by the signaled process is 
this one-word value, plus a code indicating the number of the signal. 

An Example Program 

The programs listed in Figures 7.6 and 7.7 show how to use signals as a form of 
interprocess communication. The program of Figure 7.6 first calls DosSet- 
SigHandler to install the local function SignalHandler as a handler for signal 
A. It then executes the program in Figure 7.7 as a child process, and calls 
DosCWait to pause until the child terminates. While it is waiting, Signal- 
Handler will receive control whenever the child process sends signal A. 

The child process first obtains the process ID of its parent by calling 
DosGetPid. Once it has obtained this ID, it sends signal A to its parent pro¬ 
cess by calling DosFlagProcess. It passes a value of 99 (an arbitrary num¬ 
ber) as the argument to be given to the signal handler. 

When these programs are run, the signal handler in the parent process 
immediately receives control and prints the argument passed by the child 
(99) as well as the number of the signal (5). 
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Figure 7.6 

This program shows how to write and install a signal handler to receive 
a general-purpose signal from another process. Note that FIG7_7.EXE is 
executed as a child process. You can prepare this program using the 
following command lines 

cl /G2 /Zp /Lp fig7_6.c 

Eine INCL_DOS 
Eine INCL_SUB 
:lude <os2.h> 

:lude <stdio.h> 
ulude <conio.h> 
rlude <process.h> 

^lude <string.h> 

/* Declaration of signal handler. * 

i far pascal SignalHandler (unsigned Argument, unsigned Number); 

Lgned Error; /* For saving API error codes. * 

/* Address of old signal handler. * 

1 (far pascal *01dHandler)(unsigned int,unsigned int); 

Lgned OldAction; /* Action of old signal handler. * 


void main () 

{ 

char ObjectName [13]; 
RESULTCODES ExecResult; 
RESULTCODES WaitResult; 
unsigned ProcessID; 


/* Used by DosExecPgm. 
/* Used by DosExecPgm. 
/* Used by DosCWait. 

/* Used by DosCWait. 


/*** Install the signal handler for general purpose signal A. ***************/ 
Error = DosSetSigHandler 

(SignalHandler, /* Address of new signal handler. */ 

ScOldHandler, /* Address to place address of old handler. */ 

&01dAction, /* Address to place action of old handler. */ 

2, /* Install new handler. */ 

5); /* General-purpose signal A. */ 

if (Error) 

fprintf (stderr,"Error %d calling DosSetSigHandler\n",Error); 
exit (1); 

> 

j *** Execute a child process that will send a signal. ***********************/ 
Error = DosExecPgm (ObjectName,sizeof (ObjectName),2,0,0,SExecResult, 
"FIG7_7.EXE"); 

if (Error) 

fprintf (stderr,"Error %d calling DosExecPgm; Object = %s\n", 

Error,ObjectName); 

exit (1); 

} 

/*** Wait until the child process has terminated before exiting. ************/ 
DosCWait (l,0,&WaitResult,&ProcessID,ExecResult.codeTerminate); 

} /* end main */ 


FIOURE 7.6: A program showing how to install a signal handler 
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void 

/* 


*/ 


pascal far SignalHandler (unsigned Argument, unsigned Number) 

This function receives control when another process sends signal A 
using DosFlagProcess. 

{ 

int Row = 10; 
int Col = 25; 
char DisplayBuffer [15]; 


/*** Display signal information and wait for keyboard input. ******** 


VioWrtCharStr 

VioWrtCharStr 

VioWrtCharStr 

VioWrtCharStr 

VioWrtCharStr 

VioWrtCharStr 

VioWrtCharStr 

VioWrtCharStr 


********> 


Signal Handler Activated 

argument = 
signal number = 

<press any key to continue> 


" ,30,Row++,Col,0) 
",30,Row++,Col,0); 
",30,Row++,Col,0); 
",30,Row++,Col,0); 
",30,Row++,Col,0); 
",3 0,Row++,Col,0); 
",3 0,Row++,Col, 0) ; 
",3 0,Row++,Col,0); 


sprintf (DisplayBuffer,"%u",Argument); 

Row -= 5; Col += 19; 

VioWrtCharStr (DisplayBuffer,strlen (DisplayBuffer),Row++,Col,0) 
sprintf (DisplayBuffer,"%u",Number); 

VioWrtCharStr (DisplayBuffer,strlen (DisplayBuffer),Row++,Col,0) 
getch (); 


/*** Reset the signal handling mechanism so this signal can be sent again. **/ 
Error = DosSetSigHandler 

(0L, /* No handler installed. */ 

SOldHandler, /* Address to place address of old handler. */ 

SOldAction, /* Address to place action of old handler. */ 

4, /* Acknowledge the signal. */ 

5); /* General-purpose signal A. */ 

if (Error) 

{ 

fprintf (stderr,"Error %d calling DosSetSigHandler; Line = %d\n". 
Error,_LINE_); 

exit (1); 

> 


> /* end SignalHandler */ 


FIGUIRE 7.6: A program showing how to install a signal handler (continued) 


/* 

Figure 7.7 


This program is executed as a child process by FIG7_6.EXE. It sends 
signal A to its parent process. You can prepare this program using the 
following command lines 

cl /G2 /Zp /Lp fig7_7.c 

*/ 

#define INCL_DOS 
#include <os2.h> 


FIGURE 7.7: A child process run by the program of Figure 7.6 
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FIGURE 7.7: A child process run by the program of Figure 7.6 (continued) 






























































































































































































































































CHAPTER 


Main System 
Functions 


The two chapters in Part Four provide an overview of the OS/2 appli¬ 
cation program interface (API). The API consists of a large number 
of services that are provided by the operating system and can be called 
directly by application programs. This chapter describes the general- 
purpose system functions named with the Dos prefix; Chapter 9 sum¬ 
marizes the OS/2 subsystem functions for managing specific devices: 
the keyboard (Kbd functions), the screen (Vio functions), and the 
mouse (.Mou functions). 

Chapter 2 introduced the API and explained how to call these 
services from an application program; also, Chapters 4 through 7 
described many of the individual functions and provided numerous 
examples illustrating their use. The present chapter and Chapter 9 
serve two primary purposes. First, these chapters provide an introduc¬ 
tion to the API functions that are not treated elsewhere in the book— 
functions that are either closely related to their MS-DOS counterparts 
or are beyond the scope of the book. Second, these chapters offer a 
general overview of the API and divide the large number of API func¬ 
tions into manageable groups of services that perform related tasks. 
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PROGRAM 

STARTUP 

INFORMATION 


The summaries given here will help you select the appropriate functions for 
your needs, will clarify how the functions work together, and will explain 
the proper calling sequence. Once you have chosen a function and have 
planned a general strategy for using the function within your program, you 
should then look up the detailed description in an alphabetical reference 
such as Appendix B or the Microsoft OS/2 Programmer's Reference (cited 
in the Bibliography). Note that every Dos function is included in at least one 
category described in this chapter. Some Dos functions, however, can be 
used for several different types of tasks and are therefore included in more 
than one category. 

This chapter summarizes the Dos API functions according to the follow¬ 
ing categories: 

♦ Program startup information 

♦ Memory management 

♦ Disk file and character device I/O 

♦ Disk, directory, and file management 

♦ Low-level device control 

♦ Multitasking of threads 

♦ Multitasking of processes 

♦ Multitasking of screen groups 

'♦ Interprocess communication 

♦ Time and date management 

♦ National language support 

♦ Run-time dynamic linking 

♦ Device monitor management 

♦ Error handling 

♦ Miscellaneous functions 


Table 8.1 lists a set of OS/2 functions that a program can call to obtain 
information regarding the hardware and software setting in which it is run¬ 
ning. A program typically calls these functions when it first begins execut¬ 
ing so that it can make any necessary adjustments based upon its run-time 
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Function 

V 

Purpose 

▼ 

DosGetEnv 

Obtains the selector of the environment segment 
belonging to the current process, and the offset of 
the program command line within the 
environment. 

DosGetlnfoSeg 

Obtains selectors to the global information 
segment and to the local information segment 
belonging to the current process. 

DosGetMachineMode 

Returns a flag indicating whether the machine is 
currently running in the real or protected 
processor mode. 

DosGetVersion 

Obtains the version number of the operating 
system. 

DosScanEnv 

Searches the program’s environment for a 
specified variable and, if found, returns the string 
that is assigned to this variable. 

DosSearchPath 

Searches a path for a file; the function will either 
accept a literal search path or use the path 
assigned to a specified environment variable. 


TABLE 8.1: OS/2 Functions for Obtaining Program Startup Information 


conditions. Specifically, these functions allow a program to perform the 
following general tasks: 

$ Extract information from the process environment (DosGetEnv, 
DosScanEnv, DosSearchPath) 

♦ Obtain a wide range of global system information, as well as infor¬ 
mation specific to the current process (DosGetlnfoSeg) 

♦ Obtain the operating-system version (DosGetVersion) and deter¬ 
mine whether the program is running under the real or protected 
processor mode (DosGetMachineMode) 

All of these functions—except DosSearchPath—were described in 
Chapter 2, in the section entitled Program Entry Conditions (see also Fig¬ 
ure 2.8 for an example program). DosSearchPath is included in this group 
because it extracts information from the process environment; you can use 
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it to look for a file by following a search path that it obtains from the envi¬ 
ronment (if you pass this function the name of an environment variable 
such as DPATH, it will search the directory path given by the string cur¬ 
rently assigned to this variable). 

Note that a dual-mode program may find itself running under either OS/ 
2 or MS-DOS; DosGetVersion, therefore, returns a value of 10.0 for OS/2 
version 1.0 to distinguish this system from MS-DOS. Obtaining a version 
number greater than or equal to 10.0, however, does not indicate that the 
program is running in protected mode, since it could also be running in the 
DOS compatibility box of OS/2 (which likewise returns a value of 10.0). To 
determine whether the processor is in the real or protected mode, a dual¬ 
mode program should call DosGetMachineMode. 


MEMORY OS/2 automatically allocates all code and data segments that are defined in 

MANAGEMENT the executable program file. The system also provides a set of functions for 

dynamically allocating and managing additional memory segments at run¬ 
time. These functions are listed in Table 8.2, and are divided into the follow¬ 
ing six categories: 

♦ General memory-allocation functions 

♦ Functions for discardable segments 

♦ Functions for huge memory blocks 

♦ Functions for shared segments 

♦ Functions for subsegment allocation 

♦ Functions for executing instructions in a code segment 


FuriotBOsi Purpose 

▼ V 

General Memory Allocation Functions 

DosAllocSeg Allocates a segment of memory having the specified 

size (from 1 to 65,536) and returns a selector that is 
valid within the calling process. 

DosFreeSeg Frees the memory (or relinquishes access to the 

memory) allocated by any of the OS/2 memory 


TABLE 8.2: OS/2 Functions for Managing Memory 
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Function 

Purpose 

▼ 

DosFreeSeg 

(cont.) 

allocation functions (DosAllocSeg, DosAllocHuge, 
DosAllocShrSeg, and DosCreateCSAlias). 

DosMemAvail 

Supplies the size of the largest block of free memory 
currently available ; note that this value is subject to 
change at any time. 

DosReallocSeg 

Modifies the size of a memory segment that has 
previously been allocated using DosAllocSeg. 

Functions for Discardable Segments 

DosLockSeg 

Locks a discardable memory segment (which is 
allocated by DosAllocSeg using a special flag) so that 
the segment cannot be discarded until DosUnlockSeg 
is called. 

DosUnlockSeg 

Unlocks a discardable memory segment previously 
locked by DosLockSeg. 

Functions for Huge Memory Blocks 

DosAllocHuge 

Allocates a block of memory consisting of one or 
more 64-kilobyte segments. 

DosGetHugeShift 

Returns the shift count used to compute the offset 
between the selectors of the individual segments in a 
huge memory allocation (see text for an explanation). 

DosReallocHuge 

Modifies the size of a block of memory allocated 
through DosAllocHuge. 

Functions for Shared Segments 

DosAllocShrSeg 

Allocates a named shared memory segment and 
returns a selector to this segment valid within the 
current process. 

DosGetSeg 

Obtains access to a giveaway shared memory segment 
allocated by another process through DosAllocSeg. 

DosGetShrSeg 

Obtains a selector to a named shared memory 
segment that is valid within the current process; this 
segment must have been previously allocated by 
another process through DosAllocShrSeg. 


TABLE 8.2: OS/2 Functions for Managing Memory (continued) 
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Function 

▼ 

Purpose 

▼ 

DosGiveSeg 

Obtains a selector for a giveaway shared memory 
segment (allocated through DosAllocSeg) that can be 
passed to another process. 

Functions for Subsegment Allocation 

DosSubAlloc 

Allocates a block of memory from a segment 
previously allocated by DosAllocSeg or 

DosAllocShrSeg and initialized through the 

DosSubSet function. 

DosSubFree 

Frees a block of memory previously allocated by the 
DosSubAlloc function. 

DosSubSet 

Initializes a segment of memory previously allocated 
by DosAllocSeg or DosAllocShrSeg so that this 
segment can be suballocated through DosSubAlloc. 
Alternatively, this function can be used to notify the 
suballocation system when a segment has changed 
size through a call to DosReallocSeg. 

Function for Executing Instructions in a Data Segment 

DosCreateCSAlias 

Obtains a selector that can be used to execute 
machine instructions located within a data segment. 


TABLE 8.2: OS/2 Functions for Managing Memory (continued) 


General Memory-Allocation Functions 

DosAllocSeg is the general-purpose memory-allocation function provided 
by OS/2. This function is used to allocate individual data segments that are 
either private to the calling process, or may be accessed by more than one 
process as giveaway shared memory (discussed in Chapter 7). When calling 
this function you must specify the segment size, which can be a value from 1 
to 64 kilobytes. The function returns a selector that can be used to address 
the segment only within the current process. The selector is an unsigned 
16-bit integer, and in the C language you can initialize a far pointer to 
address the first byte of the segment by using the macros FP_SEG and 
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FP_OFF (defined in the Microsoft C DOS.H header file), as in the follow¬ 
ing example: 

#include <dos.h> 

unsigned Selector; 

char far *SegPtr; 

DosAllocSeg 

(15000, /* A 15000-byte segment. */ 

&Selector / * Receives the segment selector. * / 

0); /* Nonshareable, nondiscardable. */ 

FP_SEG (SegPtr) = Selector; 

FP_OFF (SegPtr) = 0; 

When you have finished using the segment, you should call DosFreeSeg 
to relinquish access to the memory. This function normally returns the 
memory to the OS/2 free pool; however, a shared memory segment is 
released only after it has been freed by the last process holding a valid selec¬ 
tor. Note that if you attempt to address outside the bounds of an allocated 
segment, or address a segment that has been freed with DosFreeSeg, a 
general-protection violation results and the system aborts the offending 
process. 

Before you allocate memory, you can call DosMemAvail to determine 
the largest block of free memory available for allocation; this value, how¬ 
ever, is subject to change at any time through the actions of other processes 
in the system. Also, once you have allocated a memory segment, you can 
change its size by calling DosReallocSeg. See the section in Chapter 2 on vir¬ 
tual memory for a discussion of the hardware mechanism underlying OS/2 
memory management. 

Functions for Discardable Segments 

A discardable memory segment is one that the operating system can remove 
to make space for other segments when the supply of memory is low. You 
can create and manage discardable memory segments through the follow¬ 
ing sequence of steps: 

1. Allocate the segment using DosAllocSeg, passing the appropriate 
value in the allocation flag (the third parameter) to specify a dis¬ 
cardable segment. Immediately after calling DosAllocSeg, the 
segment will be locked so that it cannot be discarded. 
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2. When you have temporarily finished using the segment, you 
should call DosUnlockSeg to allow the operating system to discard 
the segment if it is low on memory. 

3. Subsequently, each time you need to access the segment, you 
should call DosLockSeg immediately before addressing the seg¬ 
ment and DosUnlockSeg after you have completed using this 
memory. Once DosLockSeg has been called, the segment cannot 
be discarded until DosUnlockSeg is called. If the segment has 
already been discarded, DosLockSeg will return an error message, 
and you must restore the segment by calling DosReallocSeg, speci¬ 
fying the original segment size. Note that in this case the data are 
lost, but the use of the segment can be restored without the need to 
create a new segment with DosAllocSeg. Like the DosAUocSeg 
function, DosReallocSeg automatically leaves the segment locked. 

4. When you have permanently finished using the segment, call 
DosFreeSeg. 

Discardable segments are convenient for the temporary storage of data 
that can easily be regenerated. If you were to use nondiscardable segments 
for such data, either the memory would be permanently and unnecessarily 
withheld from system use, or you would need to call DosAllocSeg and 
DosFreeSeg each time the segment was required. Discardable segments, 
however, are automatically freed only if insufficient memory is available to 
fill an allocation request; otherwise, the overhead of segment release and 
reallocation is avoided. 

Functions for Huge Memory Blocks 

Although the maximum segment size supported by the 80286 processor is 
64 kilobytes, OS/2 allows you to allocate more than one such segment with 
a single function call. Blocks of memory consisting of multiple segments are 
known as huge memory allocations. Huge memory blocks can be allocated 
and managed using the following sequence of steps: 

1. Allocate the memory by calling DosAllocHuge, which allows you 
to request any number of full 64-kilobyte segments plus a partial 
segment consisting of any number of additional bytes. DosAlloc¬ 
Huge returns a selector that can be used to address the first seg¬ 
ment only. 
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2. To obtain a selector for the second segment, you must add a spe¬ 
cial increment value to the original selector. To obtain the incre¬ 
ment value, call DosGetHugeShift, which returns a shift count', 
the increment value is generated by shifting 1 left by the value of 


the shift count, as in the following example: 

DosAllocHuge 

(2, /* Allocate 2 full 64 K segments, */ 

0x4000, /* plus 16K bytes. *1 

&Selector, /* Receives selector. */ 

10; /* Maximum number of segments for */ 

/* reallocation. */ 

0), /* Nonshareable, nondiscardable. */ 

/* ‘Selector’ may now be used to access first segment. */ 

DosGetHugeShift (&ShiftCount); /* Obtain shift count. */ 


Increment = 1 < < ShiftCount; /* Calculate increment. */ 

Selector + - Increment; /* ‘Selector’ now points to */ 

/* the second segment. */ 

Note that this example allocates a total of 144 kilobytes. 

3. Each time you add the increment value to the selector, you obtain 
a selector for the next segment belonging to the huge memory 
allocation. Therefore, the third segment allocated in the 
example above (a partial segment consisting of 16 kilobytes) can 
subsequently be accessed by adding Increment one more time to 
Selector. 

4. You can call DosReallocHuge to modify the size of the huge mem¬ 
ory allocation, up to the maximum number of segments specified 
in the call to DosAllocHuge (in the example above, the maximum 
number of segments is 10). 

5. When you are finished using the huge block, you can free this 
memory by calling DosFreeSeg. You pass this function the selector 
to the first segment in the huge block and it automatically frees all 
the segments in this block. 


Functions for Shared Segments 

OS/2 memory management functions can be used to allocate and manage 
either named shared memory segments or giveaway shared memory segments. 
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The use of these functions for both types of shared memory is described in 
the section in Chapter 7 entitled Using Shared Memory. 

Functions for Subsegment Allocation 

Once you have allocated a memory segment using either DosAllocSeg or 
DosAllocShrSeg, you can call the operating system to manage the suballo¬ 
cation of smaller blocks of memory within this segment. Suballocating and 
releasing small blocks of memory within a segment that already belongs to 
the process is more efficient than allocating and freeing entire segments 
(which requires that the operating system set up and remove entries in the 
local descriptor table). You can manage the suballocation of memory 
blocks using the following series of operations: 

1. Allocate a single segment of memory using DosAllocSeg or, for a 
shared segment, DosAllocShrSeg. The segment must be large 
enough to contain all of the smaller blocks you want to dynami¬ 
cally suballocate. 

2. Initialize the segment for suballocation by calling DosSubSet. 

3. You can now suballocate blocks of memory within this segment by 
calling DosSubAlloc, and free these blocks by calling DosSubFree. 
Note that DosSubAlloc returns the offset to the allocated block. If 
the containing segment is shared, the offset value is valid within all 
sharing processes, although each process must use its own segment 
selector. 

4. If you modify the size of the containing segment using DosReal- 
locSeg, you must notify the suballocation system by calling Dos¬ 
SubSet, specifying the new segment size. (Note, therefore, that you 
can use DosSubSet either to initialize a segment for suballocation 
or to change the size of this segment.) 

5. When you have completed using the suballocation functions, you 
can free the entire memory segment by calling DosFreeSeg. 

Note that the OS/2 suballocation functions perform a service similar to 
that provided by functions such as malloc and free in the standard C 
library. A good use for the suballocation functions is to manage the mem¬ 
ory blocks that contain queue messages. (Queues are discussed in Chapter 
7, the programs in Figure 7.4 and 7.5 use giveaway shared memory seg¬ 
ments to exchange queue data. If, however, processes use many small queue 
members, it would be more efficient to allocate a single shared memory seg¬ 
ment with DosAllocShrSeg, and then allocate and release smaller blocks for 
each queue element using the suballocation functions.) 
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Executing instructions in a Data Segment 

As explained in Chapter 2, the protection mechanisms of the 80286 pro¬ 
cessor prevent you from passing control to an address specified by a data 
segment selector. These mechanisms also prevent you from writing to an 
address specified by a code segment selector. OS/2, however, will provide a 
code segment selector that addresses the same segment as a given data seg¬ 
ment selector (this is known as an alias selector). You can use the data selec¬ 
tor to write or modify machine instructions contained in the corresponding 
data segment, and then use the code selector to pass execution control to 
these same instructions. Thus, a program can create or modify its own 
code; this technique is used by some of the high-performance graphics rou¬ 
tines within the Presentation Manager. You can use the following sequence 
of steps to create a code segment alias: 

1. Allocate a data segment using one of the OS/2 memory allocation 
functions, or obtain the selector for a data segment preallocated by 
the program loader. 

2. Pass this selector to the DosCreateCSAlias function, which returns 
a code selector to the same segment. 

3. Create or modify machine instructions using the data selector. 

4. Pass control to the routine using the code selector. 

5. When you have finished writing to the segment, call DosFreeSeg, 
passing the data selector. When you have finished executing the 
segment, pass the code selector to this same function. The system 
actually releases the segment only after both selectors have been 
freed. 

Note that you cannot obtain an alias code selector for a shared memory 
segment, a segment that is part of a huge memory allocation, or a global 
segment belonging to a dynamic-link library. 


DISK FILE km 
CHARACTER 
DEVICE 1/0 


The functions listed in Table 8.3 manage I/O to disk files or character 
devices. These functions all use file handles, which are unsigned 16-bit inte¬ 
gers that are returned by the system when a file is opened and are used to 
reference the file in subsequent calls to the system. 

The functions in this category are similar to their MS-DOS counterparts 
(note that MS-DOS and OS/2 use the same basic file system; both operat¬ 
ing systems can be installed on the same machine and share the files con¬ 
tained in a single logical volume). The brief function descriptions in this 
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Function 

Purpose 

V 

DosBufReset 

Flushes the file buffers belonging to a specified disk 
file or character device and updates the directory 
entry (for a disk file). 

DosChgFilePtr 

Moves the read/write pointer a specified distance in a 
file, and returns the new position of the pointer. 

DosClose 

Closes a disk file or character device previously 
opened with BosOpen. 

BosDupHandle 

Creates another file handle that points to the same 
file as a specified handle. You can either specify the 
number of the new handle or allow the system to use 
the first free handle. 

DosFileLocks 

Locks and unlocks regions of a file to prevent other 
processes from simultaneously accessing these 
regions. 

DosNewSize 

Modifies the length of the specified file, either 
truncating the file or adding disk sectors as required. 

DosOpen 

Grants access to a specified file (a disk file or device) 
and returns a handle that is subsequently used to 
refer to the file. 

BosQFHandState 

Reports the state of a specified file handle; namely, 
the read/write access mode, the sharing mode, the 
inheritance flag, the fail-on-error flag, the 
write-through flag, and the 
direct-access-storage-device flag. 

BosQFilelnfo 

Obtains information regarding the specified file, such 
as the date and time of creation or last access to the 
file, the size of the file, and the file attributes (such as 
normal or read-only). 

BosQHandType 

Indicates whether a specified handle refers to a file, a 
device, or a pipe. 

BosRead 

Reads a specified number of bytes from a file or 
device into a program buffer; this function returns 
control after the read operation has completed. 


TABLE 8.3: OS/2 Functions for Disk File and Character Device I/O 
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Function 

Purpose 

DosReadAsync 

Reads a specified number of bytes from a file or 
device into a program buffer; this function returns 
control immediately and clears a RAM semaphore 
when the read operation has completed. 

DosSetFHandState 

Modifies the state of the specified file handle; 
specifically this function can set the inheritance flag, 
the fail-on-error flag, and the write-through flag. 

DosSetFilelnfo 

Sets the time and date information for the specified 
file. 

DosWrite 

Writes a specified number of bytes to a file or device 
from a program buffer; this function returns control 
after the write operation has completed. 

DosWriteAsync 

Writes a specified number of bytes to a file or device 
from a program buffer; this function returns control 
immediately and clears a RAM semaphore when the 
write operation has completed. 


TABLE 8.3: OS/2 Functions for Disk File and Character Device // O (continued) 

section thus emphasize the unique features provided by OS/2. The follow¬ 
ing are the basic steps for using these functions to perform I/O to a disk file 
or character device (in these descriptions, the word file refers to either a disk 
file or a character device): 

1. Open the file using DosOpen. You must pass the name of a disk 
file, or the reserved device name for a character device (the OS/2 
device names are listed in the section of Chapter 4 entitled Using 
Direct Device Control). DosOpen either creates a new file or opens 
an existing file, and returns a file handle. All of the remaining 
functions listed in Table 8.3 require that you pass this handle as a 
parameter to identify the file to the system. Note that since OS/2 
is a multitasking operating system, you must specify whether an 
opened file can be shared by other processes. 

2. You can read a specified number of bytes from the file into a pro¬ 
gram buffer by calling either DosRead or DosReadAsync. 
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BosRead does not return control until the read operation has com¬ 
pleted; DosReadAsync, however, returns control immediately and 
later clears a RAM semaphore to signal the completion of the 
requested operation. 

3. You can write a specified number of bytes from a program buffer 
to a file by calling either DosWrite or Dos Writ eAsync. DosWrite 
returns control after the write operation is complete; DosWri- 
teAsync, however, returns control immediately and later clears a 
RAM semaphore to signal the completion of the write operation. 

4. If the handle refers to a disk file (or other random access medium), 
you can position the read/write pointer by calling DosChgFilePtr. 
The read/write pointer is the position in the file where the next 
read or write operation will occur; this pointer is positioned at the 
first byte when the file is opened and is automatically advanced as 
each byte is read or written. DosChgFilePtr allows you to place the 
pointer at an arbitrary position in the file, or to move the pointer a 
specified distance forward or backward. 

5. To determine whether a given handle refers to a disk file, a device, 
or a pipe, you can call the function DosQHandType. A process 
does not know this information if the handle is inherited from its 
parent (typically, a process inherits the standard input, standard 
output, and standard error handles); calling DosQHandType tells 
the process, for example, whether it can randomly move the file 
pointer through DosChgFilePtr. 

6. You can either truncate a file or extend its length by calling 
DosNewSize. 

7. You can call DosFileLocks to lock a region of an open file to pre¬ 
vent more than one process from simultaneously accessing this 
region. DosFileLocks can also be called to unlock the region. 

8. You can duplicate an existing file handle by calling DosDupHan- 
dle. This function is especially useful for redirecting the standard 
file handles inherited by a child process, and is illustrated in Fig¬ 
ures 6.5 and 7.3. 

9. You can get or set information on a file referred to by an open 
handle through the DosQFilelnfo or DosSetFilelnfo functions. 

You can also get or set information on the file handle itself by 
calling DosQFHandState or DosSetFHandState (see Appendix B 
or the OS/2 Programmer's Reference for details). 
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10. When you have finished accessing a file, you should call DosClose 
to flush all system buffers associated with the file and to update 
the file’s directory entry. Once DosClose is called, the file handle is 
no longer valid, and the file must be reopened to obtain a valid 
handle. Alternatively, you can call DosBufReset to flush the 
buffers and update the directory entry without closing the file or 
relinquishing the file handle. 

Note that you can use the file handle functions to read from the key¬ 
board or write to the screen. You can use the standard input handle to read 
from the keyboard (provided that it has not been redirected by an ancestor 
process). You can also explicitly open the keyboard using DosOpen and the 
KBD$ reserved device name, or by calling the function KbdOpen. Similarly, 
you can write to the screen using the standard output or standard error han¬ 
dle (unless the handle has been redirected), or by passing the SCREENS 
device name to DosOpen to explicitly open the screen. As an alternative to 
performing keyboard and screen I/O through the handle functions, you 
can achieve greater control by calling the specialized OS/2 subsystem calls 
for the keyboard (Kbd functions) or for the screen (Vio functions); these 
services are described in Chapter 9. 


The functions listed in Table 8.4 manage disks, directories, and files. The 
functions that manage files differ from those discussed in the last section in 
two ways. First, these functions do not perform I/O or otherwise alter the 
contents of a file. Second, these functions reference files by name rather 
than by handle. Most of the functions in Table 8.4 are quite similar to their 
MS-DOS counterparts; this brief commentary will focus on the unique fea¬ 
tures of the OS/2 functions. 

OS/2 provides several functions for managing disk drives. First, you can 
get or set the default disk drive by calling the function DosQCurDisk or 
DosSelectDisk. The default disk drive is one of the 26 logical drive letters 
allowed by OS/2, and it is the assumed target drive for all API function 
calls that do not explicitly specify another drive. Unlike MS-DOS, however, 
in OS/2 each process has its own default drive; changing the default drive in 
one process does not affect that associated with other processes. OS/2 also 
allows you to obtain the size of a disk, the available free space, and infor¬ 
mation on the volume label by calling DosQFSInfo. The function DosSet- 
FSInfo can be used to create a new volume label. 

The OS/2 functions provided for managing directories allow you to obtain 
the default directory (DosQCurDir), set the default directory (DosChdir), 
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Function 

▼ 

Purpose 

▼ 

DosChdir 

Sets the default directory for the current process. 

DosDelete 

Erases the specified file; you cannot use wildcard 
characters in the file name specification. 

DosFindClose 

Closes a directory-search handle returned by 

DosFindFirst. 

DosFindFirst 

Searches for one or more files matching the specified 
name and file attributes; this function returns a handle 
that can be passed to DosFindNext to search for 
additional matches. 

DosFindNext 

Searches for the next file or set of files matching the 
search criteria passed to a prior call to DosFindFirst. 

DosMkdir 

Creates the specified directory. 

DosMove 

Moves a file to another directory on the same drive 
and/or renames the file. 

DosQCurDir 

Obtains the default directory for a given disk drive that 
is associated with the current process. 

DosQCurDisk 

Obtains the default disk drive associated with the current 
process. 

DosQFileMode 

Retrieves the attributes (also called the file mode ) for the 
specified file. One or more of the following attributes 
may be assigned to a file: normal, read-only, hidden, 
system, subdirectory, archived file. 

DosQFSInfo 

Obtains file system information for the specified drive. 

This function can be used to obtain either the disk size 
and available free space or the volume label and the date 
and time it was created. 

DosQVerify 

Reports whether the OS/2 verify option is active. When 
this option is active, OS/2 verifies all data written to a 
disk. 

DosRmdir 

Removes the specified directory, which must be empty 
of all files and subdirectories. 


TABLE 8.4: OS/2 Functions for Disk, Directory, and File Management 
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Function 

Purpose 

▼ 

DosSearchPath 

Searches one or more directories for a file. The 
specified file name may contain wildcard characters; the 
function will accept a literal search path or use the path 
assigned to a specified environment variable. 

DosSelectDisk 

Sets the default disk drive for the current process. 

DosSetFileMode 

Sets the attributes (also called the file mode) for the 
specified file. One or more of the following attributes 
can be assigned to a file: normal, read-only, hidden, 
system, subdirectory, archived file. 

DosSetFSInfo 

Sets the volume label for the specified disk drive. 

DosSetMaxFH 

Sets the number of file handles that can be used by the 
current process. The maximum number that can be 
specified is 255, and the default number is 20. 

DosSetYerify 

Enables the OS/2 verify option. When this option is 
active, OS/2 verifies all data written to a disk. 


TABLE 8.4: OS/2 Functions for Disk, Directory, and File Management (continued) 


create a new directory (DosMkdir), or delete an existing one (DosRmdir). 
Under OS/2 the default directory is also relative to a process, and thus chang¬ 
ing this directory for one process does not affect other processes. 

The OS/2 file management functions allow you to rename files (Dos- 
Move) or erase files (DosDelete). Also, you can either obtain the current 
attributes of a file (such as read-only ; hidden, or system) by calling DosQ- 
FileMode, or you can alter the attributes of a file by calling DosSetFile- 
Mode. Additionally, OS/2 provides a complete set of functions for finding 
files. DosSearchPath will search for a specified file according to a search 
path consisting of one or more full path names (which may include wildcard 
characters). The functions DosFindFirst, DosFindNext, and DosFindClose 
allow you to locate all files matching a given file specification (which may 
contain wildcard characters). Unlike their MS-DOS counterparts, these 
OS/2 functions allow you to retrieve information for an entire group of 
files with a single function call, and also to conduct several file searches 
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simultaneously. (DosFindFirst returns a handle that identifies a specific 
search specification; each time you pass this handle to DosFindNext, the 
system will continue the search based on the same specification, regardless 
of the last call to DosFindFirst or DosFindNext. The system can thus keep 
track of multiple pending file searches. When you are done with one of 
these handles, you should close it by calling DosFindClose.) 

OS/2 also allows you to specify the maximum number of file handles 
available to a process by calling DosSetMaxFH (the maximum number is 
255 and the default is 20). Finally, you can obtain or set the status of the ver¬ 
ify option (DosQVerify, DosSetVerify). Just as under MS-DOS, when the 
verify option is active, the system validates all data written to the disk. 


Table 8.5 lists the OS/2 functions for performing low-level device con¬ 
trol. The function DosDevConfig supplies information on the hardware 
configuration of the host system, including installed devices and the com¬ 
puter model. 

DosDevIOCtl allows you to send a function request directly to a device 
driver. Chapter 4, in the section entitled Using Direct Device Control, 
describes how to use this function, and Appendix C lists the I/O control 


Function 

v 

Purpose 

DosCLIAccess 

Grants permission to an I/O privileged routine to use 
the CLI and STI machine instructions; this function is 
not supported by OS/2 version 1.0. 

DosDevConfig 

Reports which hardware devices are installed. 

DosDevIOCtl 

Sends a control function request to a device driver. 

DosPhysicalDisk 

Retrieves the total number of partitionable disks, or 
returns a handle that can be used to control a physical 
disk drive through DosDevIOCtl. 

DosPortAccess 

Grants permission to an I/O privileged routine to 
perform I/O to ports within a specified range, and to 
use the CLI and STI machine instructions; this 
function is not supported by OS/2 version 1.0. 


TABLE 8.5: OS/2 Functions for Low-Level Device Control 
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functions supported by the standard set of OS/2 device drivers. The func¬ 
tion DosPhysicalDisk can be used to retrieve the number of physical parti- 
tionable disks installed in the system, or to obtain a handle that must be 
passed to DosDevIOCtl to request functions that directly control the physi¬ 
cal disk (category 9 functions; see Appendix C). 

The OS/2 Programmer's Reference also documents a function for grant¬ 
ing port access (DosPortAccess) and interrupt control (DosCLIAccess) to 
I/O privileged routines. Version 1.0 of OS/2, however, does not support 
these functions; I/O privileged routines are automatically granted both 
forms of permission (furthermore, under version 1.0, I/O privileged rou¬ 
tines cannot call these or any other API functions). 


Table 8.6 lists the OS/2 functions for managing multiple threads. These 
functions are described in the section of Chapter 6 entitled Multitasking of 
Threads. 


Function 

V 

Purpose 

DosCreateThread 

Starts a new thread within the current process. 

DosEnterCritSec 

Temporarily suspends all threads in a process except 
the current one. 

DosExit 

Terminates the current thread. 

DosExitCritSec 

Resumes all threads previously suspended by 
DosEnterCritSec. 

DosGetlnfoSeg 

Returns the ID and priority of the current thread, 
and indicates whether the current thread is running 
in a foreground process. It also supplies the current 
parameters used by the scheduler, such as the 
minimum and maximum time slices. 

DosGetPid 

Obtains the ID of the current thread. 

DosGetPrty 

Gets the priority class and priority level of the 
current thread, or of a thread that is specified by its 

ID. 


TABLE 8.6: OS/2 Functions for Managing Multiple Threads 
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Function 

Purpose 

V 

W 

DosResumeThread 

Restarts the execution of a thread previously 
suspended by calling DosSuspendThread. 

DosSetPrty 

Sets the priority class and priority level of a thread 
within the current process. 

DosSuspendThread 

Temporarily suspends the execution of a thread. 


TABLE 8.6: OS/2 Functions for Managing Multiple Threads (continued) 


The OS/2 functions for managing multiple processes are listed in Table 8.7. 
These functions are discussed in Chapter 6, in the section entitled Multi¬ 
tasking of Processes. 


Function 

W 

Purpose 

DosCWait 

Suspends the current thread until a child process 
terminates. 

DosExecPgm 

Executes a program as a child process, synchronously 
or asynchronously. 

DosExit 

Terminates the current process. 

BosExitList 

Adds a routine to the list of functions that the system 
will execute when the current process terminates. 

DosGetlnfoSeg 

Returns the ID of the current process, the ID of the 
parent of the current process, a flag indicating 
whether the current process is in the foreground, and 
a flag indicating whether the current process requires 
the real mode. 

DosGetPid 

Returns the ID of the current process and of the 
parent of the current process. 


TABLE 8.7: OS/2 Functions for Managing Multiple Processes 
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Function 

V 

Purpose 

W 

DosGetPrty 

Returns the priority of thread, number 1 in a specified 
process. 

DosKillProcess 

Terminates either a single process or a process 
together with all its descendants. 

DosSetPrty 

Sets the base priority either of a single child process, 
or of a child process together with all its descendants. 

DosSetSigHandler 

Installs a routine that receives control when a specific 
signal is sent to the process. 


TABLE 8.7: OS/2 Functions for Managing Multiple Processes (continued) 


You can manage multiple screen groups using the functions listed in Table 
8.8, which are discussed in Chapter 6 under the heading Multitasking of 
Screen Groups. 


Function 

Purpose 

DosGetlnfoSeg 

Returns the current foreground screen group, the 
maximum number of screen groups, the ID of the 
current screen group, and whether the current screen 
group is in the foreground. 

DosSelectSession 

Places the specified screen group in the foreground. 

DosSetSession 

Sets the operational characteristics of a child screen 
group. 

DosStartSession 

Starts a process in a new screen group. 

DosStopSession 

Terminates an individual child screen group, or all 
child screen groups. 


TABLE 8.8: OS/2 Functions for Managing Multiple Screen Groups 
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INTERPROCESS OS/2 provides the following forms of interprocess communication: 

COMMUNICATION 

♦ Shared memory 

♦ Semaphores 

♦ Pipes 

♦ Queues 

♦ Signals 

All of these forms of interprocess communication—and the API func¬ 
tions that support them—are discussed in Chapter 7. This chapter also lists 
each of these functions for reference; Table 8.2 lists the services for manag¬ 
ing shared memory and Tables 8.9 through 8.12 list the functions belonging 
to the other four categories. 


Function 

Purpose 

DosCloseSem 

Closes a system semaphore. 

DosCreateSem 

Creates a system semaphore. 

DosMuxSemWait 

Blocks the calling thread until one or more of the 
specified semaphores is cleared. 

DosOpenSem 

Opens a system semaphore that has already been 
created by another process through the DosCreateSem 
function. 

DosSemClear 

Unconditionally clears the specified semaphore and 
restarts any processes blocked on this semaphore. 

DosSemRequest 

Waits until the specified semaphore is cleared (if it is 
not already clear) and then sets this semaphore. 

DosSemSet 

Unconditionally sets a semaphore. 

DosSemSetWait 

Sets the specified semaphore and then blocks the 
current thread until another thread clears the 
semaphore. 

DosSemWait 

Waits for the specified semaphore to be cleared 
(returns immediately if the semaphore is already clear). 


TABLE 8.9: OS/2 Functions for Managing Semaphores 
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DosClose 

Closes a pipe. 

DosDupHandle 

Returns a file handle that refers to the same file as a 
specified handle; this function can be used to redirect 
the standard file handles to pipes. 

DosMakePipe 

Creates a new pipe. 

DosQHandType 

Returns a code indicating whether a given handle refers 
to a disk file, a device, or a pipe. 

DosRead 

Reads from a pipe. 

DosWrite 

Writes a specified number of bytes to a pipe. 


TABLE 8.10: OS/2 Functions for Managing Pipes 


Function 

V 

Purpose 

DosCloseQueue 

Closes the specified queue. 

DosCreateQueue 

Creates and opens a queue that is owned by the calling 
process. 

DosOpenQueue 

Makes a queue created by another process available to 
the current process; returns a queue handle. 

DosPeekQueue 

Retrieves an element from a queue without removing 
it. 

DosPurgeQueue 

Removes all elements contained in a queue. 

DosQueryQueue 

Reports the number of elements in a queue. 

DosReadQueue 

Reads and removes a queue element. 

DosWriteQueue 

Adds an element to a queue. 


TABLE 8.11: OS/2 Functions for Managing Queues 
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Function 

V 

Purpose 

T 

DosFlagProcess 

Sends one of three general-purpose signals ( A, B, or 

Q to a process. 

DosHoldSignal 

Temporarily suspends or resumes signal processing 
for the current process. 

DosSetSigHandler 

Either installs or removes a handler for a given signal, 
causes the system to ignore a signal, disallows other 
processes from sending signals, or reactivates the 
signal-handling mechanism (which is temporarily 
suspended when a signal handler receives control). 


TABLE 8.12: OS/2 Functions for Managing Signals 


Table 8.13 lists the OS/2 functions for managing the system date and time, 
and for providing timing services. You can obtain the current system time 
(in hours, minutes, seconds, and milliseconds), date, time zone, and day of 
the week by calling DosGetDateTime. You can set these same values 
through the BosSetDateTime function. Note that these same time and date 
values can also be read from the global information segment, the address of 
which is returned by DosGetlnfoSeg. 

OS/2 also provides several timing functions. First, you can suspend the 
execution of the current thread for a specified number of milliseconds by 
calling DosSleep. Alternatively, you can call DosTimerAsync to start an 
asynchronous timer. This function immediately returns control to the call¬ 
ing thread and, after the requested number of milliseconds, clears a system 
semaphore. The calling thread thus continues to perform other tasks while 
the timer is running, and it can test whether the time period has elapsed by 
checking the status of the semaphore. BosTimerStart performs a similar 
service, except that the system repeatedly clears the semaphore, waiting the 
specified time period between each clearing. Both BosTimerAsync and 
BosTimerStart return handles that can be passed to BosTimerStop to halt 
the timing process. 

Note that program-timing operations can also use several of the fields in 
the global information segment accessed through BosGetlnfoSeg. In addi¬ 
tion to the time and date information mentioned at the beginning of this 
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Function 

V 

Purpose 

▼ 

DosGetDateTime 

Obtains the current time, date, time zone, and day of 
the week. 

DosGetlnfoSeg 

Supplies the address of a global information structure, 
which contains (among many other items) the current 
time, date, time zone, day of the week, a freerunning 
milliseconds counter, and the system timer interval in 
units of .0001 second. 

DosSetDateTime 

Sets the current time, date, time zone, and day of the 
week. 

DosSleep 

Suspends the current thread for the specified number 
of milliseconds. 

DosTimerAsync 

Clears a system semaphore after a specified number of 
milliseconds. 

DosTimerStart 

Starts a system timer that clears a system semaphore 
after waiting a specified number of milliseconds, 
continually repeating this process until DosTimerStop 
is called. 

DosTimerStop 

Stops a timing process that was started through 
DosTimerAsync or DosTimerStart. 


TABLE 8.13: OS/2 Time and Date Functions 


section, the system maintains a freerunning millisecond counter in the sec- 
ond field, and a counter of elapsed 0.0001-second timer intervals in 
the eighth field. See the section entitled Program Entry Conditions in Chapter 2 
for a discussion on the OS/2 global information segment; see also Figure 2.8 
for a C structure that can be used to access the fields of this segment. 
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Table 8.14 lists the OS/2 functions that provide support for different 
national languages. These functions are useful if your program is used in a 
foreign country, or if it is used to process data from another country. 

Each process under OS/2 uses a specific code page, which defines the 
character set for a particular national language. A process generally uses a 
default code page that is appropriate for the country where the computer is 
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Function 

V 

Purpose 

▼ 

BosCaseMap 

Translates the characters in a string according to the 
specified country and code page. 

DosGetCollate 

Retrieves the collating sequence table for the specified 
country and code page. 

DosGetMessage 

Retrieves a message from the specified system message 
file. 

DosGetCp 

Retrieves a list containing the current code page for the 
process, as well as all prepared system code pages. 

DosGetCtrylnfo 

Retrieves country-specific formatting information for 
the specified country and code page. 

DosGetDBCSEv 

Retrieves the double-byte character set (BBCS) 
environmental vector for the specified country and code 
page. 

DosInsMessage 

Copies a message from one buffer to another, inserting 
the specified replacement strings into the resulting 
message. 

DosPutMessage 

Writes a given message string to a specified file (or 
standard output/standard error). 

DosSetCp 

Selects a code page for the current process. 


TABLE 8.14: OS/2 Functions for National Language Support 


installed; however, a process can switch to an alternative code page. OS/2 
also maintains country-specific information, such as the time and date for¬ 
matting conventions and the collating sequence. See the OS/2 Setup Guide 
for a general description of national language support under OS/2, and for 
documentation on the CODEPAGE, COUNTRY, and DEVINFO configu¬ 
ration commands, which install specific code pages and country-specific 
information. See also the OS/2 User's Reference for a description of the 
CHCP (change code page) and KEYB (specify keyboard layout) command 
line instructions. 

This section briefly introduces the national language support that is 
available to an application program through the Dos API functions. First, 
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you can call the DosGetCp function to obtain the current code page as well 
as a list of other code pages installed in the system. You can change to a spe¬ 
cific code page by calling DosSetCp; note that changing code pages affects 
only the current process and child processes that it subsequently creates (a 
child process inherits the code page belonging to its parent). 

You can also retrieve country-specific information that corresponds to a 
specific country code and code page identifier. DosGetCtrylnfo obtains the 
formatting conventions used for times, dates, and currency amounts; 
DosGetCollate retrieves the collating sequence. BosCaseMap uses a speci¬ 
fied code page to translate the characters in a given string. Finally, 
DosGetDBCSEv supplies information for DBCS-based (double byte char¬ 
acter set) languages, such as Kanji (see the OS/2 Programmer’s Reference). 

OS/2 also supports message files. A message file contains a set of 
messages—identified by number—that can be displayed by a program. 
Placing all messages in a single file facilitates translating the program to a 
foreign language. First, DosGetMessage can be used to retrieve a message 
from a message file; this function can optionally insert a specified set of 
substitute strings into the resulting message. DosPutMessage can be used to 
write a string to a file; if the specified file is the standard output or standard 
error file, the system displays the message on the screen (provided these 
file handles have not be redirected) and automatically wraps words so that 
they will not be broken at column 80. Also, the DosInsMessage function 
can be used to copy a message from one buffer to another and insert the 
specified replacement strings into the resulting message. (Note that the pos¬ 
itions for replacement strings in the message file are indicated with the ex¬ 
pression %n where n is a number from 1 to 9 that indicates the specific 
replacement string.) 

Note that you can use the Microsoft MKMSGF utility to prepare a 
message file, and you can use the MSGBIND utility to bind a message to 
an executable file. For more information on these utilities, see the OS/2 
Programming Tools manual. 


RUN-TIME 

DYNAMIC 

LINKING 


Table 8.15 lists the OS/2 functions for managing run-time dynamic linking. 
Most of these functions were introduced in the section in Chapter 2 on 
dynamic linking, which explained the run-time dynamic linking mechanism 
as well as the more conventional load-time dynamic linking process. Chap¬ 
ter 10 explains how to develop and use dynamic-link libraries and explains 
all of the functions in Table 8.15. 
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DEVICE 

MONITOR 

MANAGEMENT 


Function 

Purpose 

V 

▼ 

DosFreeModule 

Frees the specified dynamic-link module. 

DosGetModHandle 

Supplies a handle to a dynamic-link module that has 
already been loaded. 

DosGetModName 

Accepts a handle for a dynamic-link module and 
returns the drive, path, and file name of this 
module. 

DosGetProcAddr 

Obtains the address of a given procedure within a 
dynamic-link module. 

DosLoadModule 

Loads the specified dynamic-link module and 
returns a handle. 


TABLE 8.15: OS/2 Functions for Run-Time Dynamic Linking 


Table 8.16 lists the OS/2 functions for managing character device moni¬ 
tors. These functions are thoroughly described in Chapter 11. 


Function 

▼ 

Purpose 

V 

DosMonClose 

Closes the specified monitor. 

DosMonOpen 

Opens a monitor for a specified device and returns a 
handle. 

DosMonRead 

Reads data records from the device associated with the 
monitor, and places the data in a specified buffer. 

DosMonReg 

Registers a monitor, creating the input and output buffers 
and placing the monitor in the chain of other monitors for 
the same device. 

DosMonWrite 

Writes data records to the device associated with the 
monitor from a specified buffer. 


TABLE 8.16: OS/2 Functions for Managing Device Monitors 




Main System Functions 


ERROR 

HANDLING 


OS/2 supplies several functions for managing errors. These functions are 
listed in Table 8.17. 


Function 

Purpose 

V 

V 

DosErrClass 

Supplies the classification, recommended action, and origin 
for an error code returned by an OS/2 function. 

DosError 

Disables and enables hard-error handling and the display of 
exception messages for a process. 

DosSetVec 

Installs or removes a handler for a specified processor 
exception. 


TABLE 8.17: OS/2 Functions for Handling Error Conditions 


If you receive an error code from any OS/2 API function, you can pass this 
code to DosErrClass, which will return the following items of information: 

♦ The classification of the error, which indicates the general type of 
the error. Examples of error classifications are application errors, 
internal errors, incorrect media errors, and temporary errors. 

♦ The recommended action that the process should take in response 
to the error. Examples of recommended actions are to terminate in 
an orderly manner, to terminate immediately, and to ignore the 
error. 

♦ The origin of the error. Examples of origins are a random access 
device (typically a disk drive), a network, and a serial device. 

The DosError function allows you to disable or enable hard-error pro¬ 
cessing for the current process. A hard error is one that is not under soft¬ 
ware control, such as attempting to write to a printer that is off-line. If 
hard-error processing is enabled, the system prints an error message and 
prompts the user for input. If hard-error processing is disabled, then all 
OS/2 functions that encounter a hard error will return an error code to the 
calling process. The calling process should then call OosErrClass to obtain 
complete error information. Disabling hard-error handling, therefore, 
allows the process itself to manage hard errors; note that this mechanism 
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differs from MS-DOS, under which a process must install an interrupt 24h 
service routine to manage its own hard errors. 

You can also use DosError to prevent the system from displaying an 
error message when a processor exception occurs; a processor exception is 
an error condition detected by the CPU that causes activation of an inter¬ 
rupt routine. Note, however, that even if you have used DosError to disable 
exception handling, the system will still terminate the process when an 
exception occurs. To prevent the system from terminating the current pro¬ 
cess, you must install your own exception handler by calling DosSetVec. 
The DosSetVec function allows you to install an exception handler for any 
of the following interrupts: 

INTERRUPT EXCEPTION 

0 Divide error 

4 Overflow 

5 Bound violation 

6 Invalid opcode 

7 Processor extension not available 

16 Processor extension error 


MISCELLANEOUS There are several OS/2 functions that do not fit into any of the categories 
FUNCTIONS previously described. These functions are listed in Table 8.18. 


Function 

Purpose 

V 

▼ 

DosBeep 

Creates a sound having a specified frequency and 
duration from the system speaker. 

DosPTrace 

Provides access to OS/2 debugging functions. 

DosSystemService 

Provides access to several system functions designed 
primarily for the session manager. 


TABLE 8.18: Miscellaneous OS/2 Functions 
































































































































































CHAPTER 


Screen, 
Keyboard, 
and Mouse 
Functions 


This chapter continues the overview of the OS/2 application program 
interface with a summary of the subsystem functions for the screen, 
keyboard, and mouse. These services form a comprehensive and flexi¬ 
ble extension to the basic kernel functions described in Chapter 8. The 
overview provided here will help you select the appropriate functions 
for your needs and will clarify the correct calling sequence. Once you 
have planned how to use these functions within your application, you 
can refer to Appendix B for the exact calling protocols, data types, 
and an explanation of each parameter. 
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SCREEN 

FUNCTIONS 


The OS/2 video subsystem provides a large, flexible, and high-performance set 
of functions for managing the screen display. These functions are contained 
in a dynamic-link library supplied with the system, and they are all named 
with the Vio prefix. 

The Vio functions are not the only means for producing video output 
under OS/2; there are two other important methods for writing to the 
screen. First, the Dos Write function, discussed in the last chapter, can be 
used to write a simple stream of data to the screen at the current cursor 
position. The Vio functions, however, offer a much greater level of con¬ 
trol. Second, the Presentation Manager offers an extensive set of graphics 
routines that can be used by programs written specifically for its interface 
(see Chapter 12). The Vio functions offer little direct support for graph¬ 
ics; rather, they are designed primarily for text mode programs. The Vio 
functions are especially useful for converting text mode MS-DOS pro¬ 
grams to the protected mode of OS/2; in fact, the Vio subsystem forms a 
superset of the video functions supplied by MS-DOS and the PC BIOS, 
which are familiar to most MS-DOS programmers. 

Although none of the video functions produces graphics output, the 
Vio subsystem allows programs to switch into graphics modes and pro¬ 
vides methods for directly manipulating video refresh memory and video 
controller registers. Applications can thus manage their own graphics dis¬ 
plays. The cost of such direct manipulation of the hardware is a degree of 
machine dependence and possible restriction of the user’s ability to switch 
among screen groups. Microsoft anticipates that most graphics applica¬ 
tions will eventually be converted to the Presentation Manager. 

An important benefit of the Vio subsystem is that programs using this 
interface can run within a window of the Presentation Manager. (How¬ 
ever, as explained later in the chapter, these programs must not use func¬ 
tions that switch video modes, directly manipulate the logical or physical 
video buffers, or directly program the video controller registers.) When 
an application is run under the Presentation Manager, the Vio functions 
are automatically replaced with functions that translate character output 
into the appropriate bit-mapped images. 

The great majority of Vio functions belong to the Family API (see Chap¬ 
ter 5); thus, using this interface you can write a single application that will 
run under MS-DOS, in the compatibility box of OS/2, in a protected mode 
screen group, or within a window of the Presentation Manager! 

This section divides the video functions into the following categories: 


♦ Character and attribute display 

♦ Cursor control 
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♦ String I/O 

♦ Scrolling 

❖ Mode and font control 

♦ Logical buffer management 

❖ Physical buffer management 

♦ Pop-up screen management 

❖ Routine replacement 

❖ Miscellaneous services 

Note that the video routines are used in many of the programs in this 
book. Specifically, see Chapter 10 for examples of using these functions to 
develop dynamic-link routines for managing windows and data input 
screens. 

Character and Attribute Display 

OS/2 provides three functions that can be used to write one or more copies 
of a given character and/or video display attribute starting at a specified 
position on the screen (see Table 9.1). Note that each character on the screen 
has its own display attribute. VioWrtNChar writes copies of a given charac¬ 
ter without changing the existing screen display attributes. VioWrtNAttr 


Function 

V 

Purpose 

W 

VioWrtNAttr 

Writes one or more copies of a specified video display 
attribute starting at given row and column position on 
the screen; does not affect the existing characters. 

VioWrtNCell 

Writes one or more copies of a specified character and 
display attribute combination starting at a given row and 
column position on the screen. 

VioWrtNChar 

Writes one or more copies of a specified character 
starting at a given row and column position on the 
screen; does not affect the existing video attributes. 


TABLE 9.1: Functions for Character and Attribute Display 
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writes copies of a given attribute without changing the existing characters 
on the screen. VioWrtNCell writes copies of a character and attribute com¬ 
bination known as a cell A cell consists of two contiguous unsigned bytes, 
the first of which represents the character and the second the display attrib¬ 
ute. Note that rows and columns are numbered beginning with 0; row 0 is at 
the top of the screen, and column 0 is at the left of the screen. Also, if the 
requested output does not fit on a single line, these functions continue writ¬ 
ing on the next line; however, output will not continue past the last line on 
the screen. 

The following are the attribute codes for a monochrome system: 

CODE SIGNIFICANCE 

0x00 Black character 

0x01 Underlined 

0x07 Normal 

0x08 High intensity 

0x70 Reverse video 

0x80 Blinking or high-intensity background (depending on the setting 

specified by VioSetState) 

The following are the attribute codes for a color system: 

CODE SIGNIFICANCE 

0x00 Black foreground 

0x01 Blue foreground 

0x02 Green foreground 

0x04 Red foreground 

0x08 High-intensity foreground (lightens color) 

0x10 Blue background 

0x20 Green background 

0x40 Red background 

0x80 Blinking or high-intensity background (depending on the setting 

specified by VioSetState) 

Note that when you specify an attribute for a video function, you can 
combine one or more of the above attribute codes using the logical OR 
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operator (provided that the combination makes sense and is supported by 
the hardware). 

The following example writes 15 spaces, with the reverse video attrib¬ 
ute on a monochrome system, beginning at row 5 and column 10: 


char Cell [2]; 


Cell [0] = ”; 


Cell [1] = 0x70; 


VioWrtNCell 


(Cell, 

/* Address of cell. 

15, 

/* Write 15 copies. 

5, 

/* Row 5. 

10, 

/* Column 10. 

0); 

/* Video handle: always 0. 


Cursor Control 

The video functions for controlling the position and shape of the cursor 
are listed in Table 9.2. 


Function 

V 

Purpose 

V 

VioGetCurPos 

Obtains the row and column position of the cursor on 
the screen. 

VioGetCurType 

Obtains the current height, width, and display 
attribute of the cursor. 

VioSetCurPos 

Places the cursor at the specified row and column 
position on the screen. 

VioSetCurType 

Sets the height, width, and display attribute of the 
cursor. 


TABLE 9.2: Functions for Cursor Control 


You can obtain the current row and column position of the cursor by 
calling VioGetCurPos, and you can place the cursor at a specific row and 
column by calling VioSetCurPos. You can also get or set the cursor shape 
and display attribute by calling VioGetCurType or VioSetCurType. Note 
that the shape is specified by the starting and stopping horizontal lines of 
pixels used to form the cursor, and by the cursor width. 
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Setting the cursor position is especially useful in conjunction with video 
functions that do not accept a screen position, such as VioWrtTTy, which 
writes a character string beginning at the current cursor position. 

String I/O 

Table 9.3 lists the video functions for managing the input and output of 
strings from the screen. 

VioWrtTTy is an important function for writing a string to the screen. 
This function has the following unique properties: 

♦ The string is written starting at the current cursor position. 

♦ The string is displayed using the video attribute at the current 
cursor position. 


Function 

V 

Purpose 

V 

VioReadCellStr 

Reads a sequence of character/attribute pairs (cells) 
from the screen into a buffer, beginning at a 
specified row and column screen position. 

VioReadCharStr 

Reads a character string (consisting of characters 
only) from the screen into a buffer, beginning at a 
specified row and column screen position. 

VioWrtCellStr 

Writes a string consisting of a sequence of 
character/attribute pairs (cells), beginning at a 
specified row and column screen position. 

VioWrtCharStr 

Writes a string consisting of a sequence of characters 
only, beginning at a specified row and column screen 
position. This function does not alter the existing 
screen attributes. 

VioWrtCharStrAtt 

Writes a string consisting of a sequence of characters 
only, beginning at a specified row and column screen 
position. This function uses a single specified display 
attribute to write all the characters. 

VioWrtTTy 

Writes a string starting at the current cursor position, 
using the attribute at the cursor position. 


TABLE 9.3: Functions for String I/O 
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* The cursor position is updated as the string is written. 

❖ If the string reaches the end of a row, it will he continued on the 
next line (like the other functions in this module); also, if the 
string goes past the bottom of the screen, the screen is scrolled up 
(unlike the other functions). 

❖ The function responds to the following embedded control char¬ 
acters: backspace (0x08), tab (0x09), linefeed (OxOA), return 
(OxOD), and bell (0x07). 

♦ If ANSI escape sequences are activated for the screen group (see 
the VioSetAnsi function), this function responds to ANSI com¬ 
mands embedded in the string. 

DosWrite, when it is used to write to the screen, performs the same 
action as VioWrtTTy (in fact, when output is directed to the screen, 
DosWrite calls VioWrtTTy). However, when DosWrite writes to the stan¬ 
dard output or standard error handles, it is subject to redirection, whereas 
VioWrtTTy always writes to the screen. Note, therefore, that there is 
some danger in using the Vio functions if several processes share the same 
screen group. A parent process may redirect the standard output of a child 
process to a disk file so that the parent can continue to write to the screen 
without interference from the child. If, however, the child process 
bypasses the redirection mechanism by using the Vio functions, its output 
may conflict with that of its parent. To help avoid this problem, a process 
can call DosQHandType to determine if standard output has been redi¬ 
rected to a disk file; if it has been redirected, then the process should use 
standard output rather than writing directly to the screen through the Vio 
functions, since its parent may be writing to the screen at the same time. 

The other three functions in this group for displaying strings (VioWrt- 
CellStr, VioWrtCharStr, and VioWrtCharStrAtt) all write a string to a 
specified row and column position, do not update the cursor position, do 
not cause the screen to scroll, and do not respond to control codes or 
ANSI escape sequences. VioWrtCellStr writes a string consisting of a 
sequence of character/attribute pairs (cells), and VioWrtCharStr writes a 
string consisting of characters only, without modifying the existing screen 
attributes. Finally, VioWrtCharStrAtt writes a string composed of charac¬ 
ters only, using a single specified attribute. 

The function VioReadCharStr reads a character string from a given 
position on the screen; this function reads the characters only and not the 
attributes. VioReadCellStr, however, reads both the characters and the 
attributes from the screen. VioReadCellStr, together with VioWrtCellStr, 
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provide a convenient means for saving and restoring sections of the screen 
(for example, when temporarily displaying a window on top of a screen 
display). 

Scrolling 

OS/2 provides functions for scrolling a rectangular section of the screen 
in any direction. These functions are listed in Table 9.4. 

With all of these functions, you can specify the number of rows or 
columns to scroll, as well as a character and attribute pair (a cell) to be 
used to fill the area of the screen that is exposed as the data is moved. 
A.ny of these functions can be used to clear a section of the screen—or 
the entire screen simply by specifying a blank-fill character and 
requesting the function to scroll the total number or lines or columns in 
the area. Note that if you specify screen coordinates or a number of lines 
larger than the maximum possible values, the scrolling function will sim- 
ply use the maximum values. Therefore, the safest way to clear the entire 
screen is to use the maximum values, as in the following function call 


Function 

V 

Purpose 

V 

VioScrollDn 

Scrolls down the specified rectangular section of the 
screen, inserting a given number of lines consisting of a 
specified character and attribute at the top of the screen. 

VioScrollLf 

Scrolls left the specified rectangular section of the screen, 
inserting a given number of columns consisting of a 
specified character and attribute at the right of the screen. 

VioScrollRt 

Scrolls right the specified rectangular section of the screen, 
inserting a given number of columns consisting of a 
specified character and attribute at the left of the screen. 

VioScrollUp 

Scrolls up the specified rectangular section of the screen, 
inserting a given number of lines consisting of a specified 
character and attribute at the bottom of the screen. 


TABLE 9.4: Functions for Scrolling Areas of the Screen 
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(these parameters will clear the screen regardless of the number of lines 
and columns currently displayed): 

VioScrollDn 


(0, 

/* Top row. 

o, 

/* Left column. 

Oxffff, 

/* Maximum row value. 

Oxffff, 

/* Maximum column value. 

Oxffff, 

/* Maximum number of lines on screen. 

“ \x07”, 

/* Blank character/normal attribute. 

0); 

/* Video handle: must be 0. 


SVIode and Font Control 

Table 9.5 lists a set of functions for controlling the video state and the 
fonts used to display characters on the screen. 


Function 

V 

Purpose 

V 

VioGetConfig 

Retrieves the type of video adapter, the type of monitor, 
and the amount of video memory on the adapter. 

VioGetCp 

Retrieves the current code page being used to display text 
on the screen. 

VioGetFont 

Retrieves either the current font, or a specified font from 
the display adapter. 

VioGetMode 

Retrieves information on the current video mode. 

VioGetState 

Retrieves the current setting of the palette registers, the 
border color, or the setting of the blink/intensity switch. 

VioSetCp 

Sets the code page to be used for the current screen 
group. 

VioSetFont 

Sets the video adapter font to be used for subsequent 
screen display. 

VioSetMode 

Sets the current video mode. 

VioSetState 

Sets the palette registers, the border color, or the 
blink/intensity switch. 


TABLE 9.5: Functions for Managing the Video State and Display Fonts 
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First, you can find out the basic video hardware configuration by call¬ 
ing VioGetConfig. This function supplies the following information: 

♦ The adapter type: monochrome, CGA (color graphics adapter), 
EGA (enhanced graphics adapter), or VGA (video graphics 
array). 

♦ The monitor type: monochrome; color; EGA, 8503 mono¬ 
chrome; or an 8512, 8513, or 8514 color display. 

♦ The amount of memory on the adapter. 

Once you have ascertained the video capabilities of the hardware, you 
can call VioGetMode to obtain the current video mode or VioSetMode to 
set a new video mode that is supported by the installed hardware. Rather 
than identifying video modes by the numbers used with the ROM BIOS 
routines under MS-DOS, the OS/2 Vio routines specify a video mode in 
terms of its features. The following are the video mode features that can 
be obtained through VioGetMode or set through VioSetMode: 

♦ The screen mode, which indicates whether a monochrome 
adapter is enabled, whether a nonmonochrome adapter is 
enabled, whether a graphics mode is enabled, and whether the 
color burst is disabled. 

♦ The number of colors. 

♦ The number of text rows and columns. 

♦ The horizontal and vertical pixel resolution. 

Note that unlike the corresponding ROM BIOS function, VioSetMode 
does not clear the screen when it changes video modes. 

The Vio functions also allow you to manage lower-level features of the 
video adapter. The following features can be retrieved through the 
VioGetState function and can be set through the VioSetState function: 

♦ The settings of the palette registers. 

♦ The color of the screen border. 

♦ The state of the blink/intensity switch; this switch determines the 
effect of the high-order bit (bit 7) of the video display attribute. 
When blinking is enabled, bit 7 causes the associated character to 
blink; when intensity is enabled, bit 7 causes the background 
color to be displayed in high intensity. 
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You can obtain or set the code page used to display characters on the 
screen by calling VioGetCp or VioSetCp. See the discussion on code pages 
in Chapter 8, under the section entitled National Language Support. 
Also, you can call VioGetFont to retrieve any character font that is sup¬ 
ported by the display adapter. Finally, you can set the current video font 
by calling VioSetFont, provided that the display adapter supports this 
operation. 

Note that your program will not be able to run within a window of the 
Presentation Manager if you change video modes or perform other low- 
level video control operations with the functions listed in Table 9.5. 

Logical Buffer Management 

The video functions listed in Table 9.6 provide an alternative method for 
producing video output. VioGetBuf returns the address and size of the 
logical screen buffer associated with the current screen group. As 
explained in Chapter 1 (under the heading Protected Mode Screen 
Groups), the system maintains a logical video buffer that can hold an 
entire screen of data. While the screen group is in the foreground, all out¬ 
put to the screen is stored in the logical buffer. Therefore, when the cur¬ 
rent screen group is switched to the background, the screen contents are 
preserved in the logical buffer. While the screen group runs in the back¬ 
ground, all video output updates the logical buffer rather than the physi¬ 
cal screen, and when the screen group is switched back to the foreground, 
the current contents of the logical buffer are copied back to the physical 
screen. 


Function 

▼ 

Purpose 

▼ 

VioGetBuf 

Returns the address of the logical video buffer associated 
with the current screen group. 

VioShowBuf 

Updates the physical screen from the contents of the 
logical video buffer associated with the current screen 


group. 


TABLE 9.6: Functions for Managing the Logical Screen Buffer 


If a program obtains the address of the logical video buffer by calling 
VioGetBuf, it can write its video output to this buffer in the same manner 
that many MS-DOS programs write their video output directly to the 
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screen (actually, to the video refresh buffer located in RAM on the adapter 
card). Normally, output to the logical buffer would not be copied to the 
physical screen until the screen group switches from the background to the 
foreground. However, you can force the system to update the physical 
screen from the logical buffer at any time by calling the function 
VioShowBuf. Note that VioGetBuf returns the total size of the logical 
buffer, and VioGetMode reveals the number of screen rows and columns 
that are mapped to the buffer. 

The logical buffer is generally large enough to store only a text mode 
screen; graphics programs not written under the Presentation Manager 
must normally use the technique discussed in the next section. (The CGA 
graphics modes are an exception; when a CGA mode is active, the video 
buffer has a size of 16 kilobytes, which is large enough to contain the data 
for a graphics screen.) Note also that writing directly to the logical buffer 
precludes the program running within a window of the Presentation Man¬ 
ager. See Performance Programming Under MS-DOS, or one of the other 
MS-DOS programming guides cited in the Bibliography, for an explana¬ 
tion of how to create screen output by writing directly to video memory. 


Physical Buffer Management 

The functions listed in Table 9.7 allow programs to generate screen output 
by directly accessing the physical video refresh buffer, located on the con¬ 
troller hardware. Many high-performance MS-DOS programs use this 
technique to circumvent the notoriously slow DOS and BIOS video serv¬ 
ices. OS/2 text mode programs can use the more efficient Vio functions. 
However, OS/2 graphics programs that are not written specifically for the 
Presentation Manager will need to write directly to video memory, 
because the Vio calls do not manage graphics screens and because the 
BIOS graphics services are not available in protected mode. 

There are two primary problems with writing directly to video memory 
in the protected mode environment. First, if a process continues to write 
to video memory when it is switched into the background, it will overwrite 
the screen belonging to the new foreground screen group. OS/2 therefore 
provides a means for temporarily locking the screen group in the fore¬ 
ground. Second, when OS/2 switches screen groups, it usually will not be 
able to save and restore the entire graphics screen or the state of the video 
registers. OS/2 therefore provides a mechanism for notifying a process 
when the video data or register settings need to be saved or restored. 

The following is a brief summary of a typical sequence for using the 
functions listed in Table 9.7 to directly access video memory: 

1. Call VioGetPhysBuf to obtain a valid selector that can be used to 
address video memory. 
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Function 

V 

Purpose 

▼ 

VioGetPhysBuf 

Obtains the address and size of the physical video 
buffer. 

VioModeUndo 

Relinquishes ownership of a request made through 
VioModeWait to be notified when the video mode 
needs to be restored, or simply releases the thread 
waiting to restore the mode. The released thread is 
either terminated or allowed to continue running. 

VioModeWait 

Suspends a thread until the video mode needs to be 
restored when the screen group switches from the 
background to the foreground (for example, after a 
pop-up screen has been displayed). 

VioSavRedrawUndo 

Relinquishes ownership of a request to be notified 
of a screen switch through VioSavRedrawWait, or 
simply releases the thread waiting for a screen 
switch. The 

released thread is either terminated or allowed to 
continue running. 

VioSavRedrawWait 

Suspends a thread until the screen needs either to be 
saved or restored because of a screen group switch. 

VioScrLock 

Locks the physical screen in the foreground; also 
prevents the physical screen from being accessed by 
more than one process in the current screen group. 

VioScrUnLock 

Unlocks the physical screen after it has been locked 
by VioScrLock. 


TABLE 9.7: Functions for Managing the Physical Screen Buffer 


2. A dedicated thread should call the function VioSavRedrawWait. 
This function suspends the thread until the screen data needs to 
be saved or restored (because of a screen group switch); the 
thread should then perform the required tasks to save or restore 
the video screen data, and immediately call VioSavRedrawWait 
again. The call to this function can be canceled by another thread 
in the same process through the VioSavRedrawUndo function. 

3. Another dedicated thread should call VioModeWait. This func¬ 
tion suspends the thread until the video mode needs to be 
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restored (because of a screen group switch); the thread should 
then perform the required tasks to restore the original video 
mode and immediately call VioModeWait again. The call to this 
function can be canceled by another thread in the same process 
through the VioModeUndo function. 

4. Before writing to the screen, the process should call VioScrLock, 
which locks the screen in the foreground; when it has completed writ¬ 
ing to the screen, it should immediately call VioScrUnLock to unlock 
the screen. (You should minimize the time the screen is kept locked.) 

If the user attempts to switch the current screen group into the back¬ 
ground when the screen is locked, the system will delay the switch for 
30 seconds. If the screen has not been unlocked by the end of this 
period, then the system will perform the switch, but will suspend the 
current process in the background so that it cannot continue writing 
to video memory. (Remember that processes in background screen 
groups normally continue to run.) Note that only a single process can 
lock the screen at a given time. 

If your program needs to read or write directly to the registers belong¬ 
ing to the video controller, you will have to write an I/O privileged module 
to contain this code (see the section on this topic in Chapter 4). Note that 
programming registers or writing directly to the physical buffer will, of 
course, prevent a program from running within a window of the Presenta¬ 
tion Manager. Also, this technique may prevent the user from freely 
switching among screen groups. 

Pop-up Screen Management 

Table 9.8 lists the two OS/2 functions for managing pop-up screens. A pop¬ 
up screen allows a background process to temporarily use the screen and 


Fuoction 

Purpose 

V 

V 

VioEndPopUp 

Closes a pop-up screen and restores the previous 
screen contents. 

VioPopUp 

Saves the existing screen contents and opens a pop-up 
screen. 


TABLE 9.8: Functions for Managing Pop-up Screens 
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keyboard to display a message to the user. Normally processes in back¬ 
ground screen groups, or processes that have been permanently relegated to 
the background (through the DETACH command, for example), cannot 
write data to the physical screen. These processes, however, may need to dis¬ 
play an important message and receive a response from the user (for 
example, a background print spooler detects that the printer is off-line). 

When a background process calls VioPopUp, the system saves the con¬ 
tents of the current screen, switches into an 80-column text mode if neces¬ 
sary, and allows the background process to write to the screen and receive 
input from the keyboard. (Note, however, that not all Vio functions may 
be called from a pop-up; see the OS/2 Programmer's Reference for a list 
of the allowed functions.) When calling VioPopUp, you can request that 
the current screen contents be erased or that the current screen be left 
intact. Also, only one pop-up screen can be open at a given time; you must 
specify whether VioPopUp should return immediately (with an error mes¬ 
sage) if another pop-up screen is displayed, or whether it should wait until 
the previous pop-up is closed. 

When a process has completed displaying a pop-up screen, it should 
immediately call VioEndPopUp to close the pop-up screen. When this 
function is called, the system restores the screen contents and returns the 
former process to the foreground. 

Routine Replacement 

The functions for replacing default Vio functions are listed in Table 9.9. 
VioRegister allows you to replace one or more Vio functions with custom 
routines contained in a dynamic-link module. Once a set of functions has 


Function 

Purpose 

V 


VioDeRegister 

Restores all default Vio functions for the current 
screen group (that is, it cancels all screen function 
replacements made by VioRegister). 

VioRegister 

Replaces one or more Vio functions with routines 
within a specified dynamic-link module. Replacement 
affects only the current screen group. 


TABLE 9.9: Functions for Replacing Video Routines 
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been replaced, the system reroutes all calls to these functions to the entry 
point within your module; note that the rerouting is performed only for 
functions within the current screen group. Vio functions can be replaced 
through the following steps: 

1. Prepare a dynamic-link module containing routines that replace 
one or more Vio functions. This module must have a single entry 
point that passes control to the requested routine. Note that a 
routine that replaces a Vio function should not use other Vio 
functions to perform screen output; rather, it should use the I/O 
control functions, which are summarized in Appendix C. See also 
Chapter 10 for information on writing dynamic-link modules. 

2. Call VioRegister to replace the default functions with the rou¬ 
tines within your module, specifying the module name, the entry 
point, and a list of the functions to be replaced. A single call to 
VioRegister replaces an entire set of video routines for all proc¬ 
esses within the current screen group. See the OS/2 Program¬ 
mer's Reference for a list of the functions that can be replaced, 

3. When a process calls a replaced function, control passes to the 
entry point within your module, which must determine the 
requested function (by reading a code that the system places in 
the stack) and dispatch control to the appropriate routine. See 
the OS/2 Programmer's Reference for a description of the 
parameters passed to the entry routine and for a list of the func¬ 
tion codes. 

4. If you would like to restore all Vio functions to the default sys¬ 
tem routines, call VioDeRegister. Note that after you have called 
VioRegister, no process (including the current one) can call this 
function again to register additional functions until VioDeRegis¬ 
ter has been called. 


Miscellaneous Services 

Table 9.10 lists several video functions that do not fit into any of the other 
categories discussed in this section. 

You can call VioSetAnsi to enable or disable the processing of ANSI 
control codes by VioWrtTTy. When ANSI processing is enabled, 
VioWrtTTy processes escape sequences embedded in the output data as 
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Function 

V 

Purpose 

W 

VioGetAnsi 

Indicates whether the VioWrtTTy function currently 
processes ANSI escape sequences. 

VioPrtSc 

Prints the current contents of the screen. This 
function is called only by the system when the 
Shift-PrtSc keystroke combination is pressed. 

VioPrtScToggle 

Enables or disables screen echo to the printer. This 
function is called by the system only when the 
Control-PrtSc keystroke combination is pressed. 

VioSetAnsi 

Sets the state of the flag that determines whether the 
VioWrtTTy function processes ANSI escape 


sequences. 


TABLE 9.10: Miscellaneous Video Functions 

control signals rather than printing them as literal characters. (These 
codes are the same as those recognized by the ANSI.SYS device driver 
under MS-DOS; see the OS/2 Programmer’s Reference for a list of the 
escape sequences.) For example, the following function call uses an ANSI 
sequence to display a line in reverse video: 

char * Message; 

Message = “\x1 b[7mThis is printed in reverse video.\x1 b[0m”; 

VioWrtTTy 

(Message, /* Data containing escape sequences *1 

strlen (Message), /* Length of data. *1 

0); /* Video handle, always 0. */ 

Note that if ANSI processing were disabled, this function call would print 
the escape codes as literal characters. The function VioGetAnsi reports 
whether ANSI processing is currently enabled. 

The OS/2 video subsystem supplies two additional functions that are 
called only by the system. First, the system calls VioPrtSc whenever the 
user presses the Shift-PrtSc key combination; this function sends the cur¬ 
rent contents of the screen to the printer. Second, the system calls 
VioPrtScToggle whenever the user presses the Ctrl-PrtSc key combina¬ 
tion; this function toggles on and off the echoing of screen output to the 
printer. 
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KEYBOARD 

FUNCTIONS 


If VioPrtSc and VioPrtScToggle can be called only by the system, what 
is their value for an application program? These two functions are among 
those that can be replaced, as discussed previously in the chapter. If you 
replace one or both of these routines, the system will call your function 
rather than the default function whenever the user presses the correspond¬ 
ing key combination. The video replacement mechanism thus allows you 
to capture and process the screen-printing keystrokes. 


The OS/2 keyboard subsystem consists of a large set of functions that are 
contained in a dynamic-link library and are named with the Kbd prefix. 
The OS/2 keyboard functions form a superset of the services available 
under MS-DOS and the ROM BIOS; also, under OS/2 the keyboard 
buffer has been expanded to hold 61 bytes (the BIOS buffer under MS- 
DOS holds only 15 bytes). 

Like the OS/2 video services, the OS/2 Kbd functions are designed pri¬ 
marily for text mode programs ported from MS-DOS to the protected 
mode of OS/2. Programs that use this keyboard interface, however, can 
also run within a window of the Presentation Manager. Additionally, 
almost all the Kbd functions belong to the Family API. 

This section groups the keyboard functions into the following 
categories: 

♦ Logical keyboard management 
$ Character input 

♦ Managing the keyboard status 
$ Routine replacement 

$ Character translation 

Many of the programs in this book exemplify the use of the OS/2 key¬ 
board functions. See especially Chapter 10, which employs the keyboard 
functions in a set of dynamic-link routines for managing windows and 
data input screens. 

Logical Keyboard Management 

Table 9.11 lists the OS/2 functions for managing logical keyboards. 
Before learning about the keyboard input functions, it is important to 
understand the concept of a logical keyboard. When a screen group is in 
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Function 

V 

Purpose 

W 

KbdClose 

Closes a logical keyboard previously opened with 

KbdOpen. 

KbdFreeFocus 

Frees the focus from the specified logical keyboard that 
had previously obtained the focus by calling 

KbdGetFocus. 

KbdGetFocus 

Secures the focus for the specified logical keyboard. 

KbdOpen 

Opens a logical keyboard and supplies a handle that 
references this keyboard for subsequent function calls. 


TABLE 9.11: Functions for Logical Keyboard Management 


the foreground, all processes within this screen group share a single physi¬ 
cal keyboard. It is thus possible for the keyboard input belonging to one 
process to become intertwined with that belonging to another process. 
OS/2 therefore allows the processes within a single screen group to open 
multiple logical keyboards, and prevents more than one logical keyboard 
from accessing the physical keyboard at a given time. Note that the use of 
multiple logical keyboards is optional; any process can bypass this mecha¬ 
nism by directly referencing the physical keyboard rather than a logical 
keyboard. 

You can create and use a logical keyboard through the following 
sequence of operations: 

1. Call KbdOpen to open a logical keyboard and obtain a handle. 
When calling Kbd functions that read keyboard input or control 
the operation of the keyboard, you must pass this handle to iden¬ 
tify the specific logical keyboard. Each logical keyboard has its 
own keyboard buffer. (Note that this handle can also be used 
with normal Dos file handle functions, such as DosRead or Dos- 
DevIOCtl; see Chapter 8.) 

2. Before you can pass this handle to any of the Kbd functions, 
however, you must secure the keyboard focus for the correspond¬ 
ing logical keyboard by calling KbdGetFocus. When a logical 
keyboard owns the focus, all subsequent keystrokes are received 
in the keyboard buffer associated with this logical keyboard. 
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Note that the focus can be associated with only one logical key¬ 
board at a time. You must pass KbdGetFocus the handle 
obtained from KbdOpen, and a flag indicating whether you want 
to wait if necessary until the focus becomes available. 

3. Once you have secured the focus for a specific logical keyboard, 
you may call Kbd functions to read keyboard input or control the 
operation of the keyboard, passing these functions the appropri¬ 
ate handle. Note that if you call a Kbd function, specifying the 
handle of a logical keyboard that does not own the focus, the 
function returns an error message. 

4. When you have finished accessing the keyboard, you should 
relinquish the keyboard focus immediately by calling KbdFreeFo- 
cus, which allows other logical keyboards to obtain the focus. 

5. When you have permanently finished accessing the keyboard 
through a particular logical keyboard, you should call KbdClose 
to close the handle. 

Note that you can bypass the logical keyboard mechanism by passing a 
handle value of 0 to any Kbd function that requests a keyboard handle. 
Handle number 0 refers to the physical keyboard, and you do not need to 
secure the focus before using this handle (in other words, handle number 0 
can always be used to read characters from the current keyboard buffer or 
to control the physical keyboard). Note, however, that unlike a logical 
keyboard handle returned by KbdOpen, handle 0 does not necessarily 
refer to the keyboard when calling standard Dos handle I/O functions, 
such as DosRead (rather, handle 0 refers to the standard input, which may 
have been redirected to a disk file). 

Character input 

Table 9.12 lists the functions for reading the keyboard or flushing the key¬ 
board buffer. All of these functions require you to pass a keyboard han¬ 
dle. As explained in the previous section, to read characters from the 
current keyboard buffer you can pass either the handle of a logical key¬ 
board that owns the current focus , or you can simply pass a handle value 
of 0. In either case, if a logical keyboard currently owns the focus, all 
input comes from the buffer associated with this keyboard. 

You can read and remove a single character from the keyboard buffer 
by calling KbdCharln; this function reports not only the value of the char¬ 
acter, but also additional information on the keystroke and the status of 
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Function 

W 

Purpose 

¥ 

KbdCharln 

Reads a single character and scan code from the 
keyboard, and reports the current shift-key status; 
this function removes the character read from the 
keyboard buffer. 

KbdFlushBuffer 

Flushes all characters from the keyboard buffer. 

KbdPeek 

Reads a single character and scan code from the 
keyboard, and reports the current shift-key status; 
this function does not remove the character read 


from the keyboard buffer. 

KbdStringln 

Reads a string of characters from the keyboard. 


TABLE 9.12: Functions for Character Input 


the keyboard. The following are among the items of information returned 
by KbdCharln: 

♦ The character value; the system computes this value based upon 
the scan code (identifying the actual key that was pressed), the 
status of the shift keys (such as the Shift or Control key), and the 
current translation table. If a keystroke does not have a normal 
character value (such as an arrow key), this field is set to OOh or 
EOh, and you must look at the next field to identify the key. 

♦ An extended code. This code is useful for identifying keystrokes 
that do not yield a character value; see the OS/2 Programmer's 
Reference for a table of these codes. 

♦ The time in milliseconds when the keystroke was entered. 

♦ The current status of the shift keys, such as Shift, Control, 
and Alt. 

When calling KbdCharln, you must pass a flag indicating whether the 
function should wait if necessary until a key is available, or whether it 
should return immediately, either retrieving a key or reporting that no key is 
available. Note that while waiting for a keystroke, KbdCharln blocks the 
current thread and does not consume processor cycles; if, however, you 
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were to wait for a keystroke by repeatedly calling KbdCharln, specifying 
the “no wait” option, processor cycles would be wasted and the efficiency 
of other processes in the system would be reduced. 

Note that KbdCharln does not echo to the screen the characters that it 
reads. You can call VioWrtTTy immediately after each call to KbdCharln to 
echo the character read at the current cursor position. 

You can also read a single character from the keyboard by calling Kbd- 
Peek. This function reports the same information as KbdCharln; it does 
not, however, remove the character from the keyboard buffer. Also, Kbd- 
Peek always returns immediately, either supplying a key or reporting that 
no key is available. 

You can read an entire character string from the keyboard into a pro¬ 
gram buffer with a single call to the function KbdStringln. This function 
has the following important properties: 

♦ You pass the length of the receiving buffer, and KbdStringln 
reports the actual number of characters read. 

♦ KbdStringln reads characters until the user presses the turnaround 
key (normally Enter), or until the receiving buffer is filled (when 
the number of characters entered is one less than the buffer length, 
the function allows the user to enter only the turnaround key or a 
backspace, and it beeps if the user attempts to type other key¬ 
strokes). 

♦ If the keyboard is in the cooked mode (explained in the next sec¬ 
tion) the function responds to OS/2 control codes (such as 
Control-C and Control-S) and recognizes the OS/2 editing keys. 
(See the OS/2 User's Reference for a description of the editing 
keys.) 

♦ You must pass a flag to KbdStringln specifying whether the func¬ 
tion should wait for the turnaround character to be entered, or 
whether it should return immediately with whatever characters are 
currently available in the keyboard buffer. See the comments on 
the wait option for KbdCharln, given above. 

♦ If the keyboard is in the cooked mode and the echo option is active 
(explained in the next section), characters are echoed to the screen 
as they are entered. 

Note that KbdCharln, although it prevents the user from entering more 
than the requested number of characters, does not neatly confine its echoed 
output to a defined area of the screen (for example, if the user presses 
Escape, subsequent characters are echoed to the next line on the screen.) 
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Therefore, this function is not suitable for receiving input from a carefully 
designed data entry screen. For an alternative routine that is suitable for 
data entry screens or windows, see Chapter 10. 

Note also that DosRead, when it is used to read from the keyboard, 
works in the same manner as KbdStringln. However, when DosRead is used 
to read from standard input, it is subject to redirection, whereas Kbd¬ 
Stringln always reads from the keyboard. You must therefore be careful not 
to defeat an attempt by the parent process to redirect the input of the cur¬ 
rent process (see the comments on VioWrtTTy in the section on String I/O, 
earlier in this chapter). 

Finally, you can flush all waiting characters from the keyboard buffer by 
calling KbdFlushBuffer. Note that if a logical keyboard owns the focus 
when this function is called, only the buffer associated with this keyboard is 
flushed; the characters in any other buffers remain intact. 

Managing the Keyboard Status 

Table 9.13 lists the two functions for managing the keyboard status. The 
following keyboard parameters can be obtained by calling KbdGetStatus or 
set by calling KbdSetStatus: 

$ Whether characters will be echoed to the screen by KbdStringln. 

❖ Whether the input mode is cooked or raw . In cooked mode, Kbd¬ 
Stringln and KbdCharln process all OS/2 control keys (for 
example, Control-C and Control-S) and KbdStringln responds to 
all editing keys. In raw mode, these functions treat all keystrokes 
as literal characters, except Control-Break. 


Function 

▼ 

Purpose 

KbdGetStatus 

Reports the status of the keyboard, including the 
echo mode, the input mode (raw or cooked), the 
turnaround character, and the status of the shift keys. 

KbdSetStatus 

Sets the status of the keyboard, including the echo 
mode, the input mode (raw or cooked), the 
turnaround character, and the status of the shift keys. 


TABLE 9.13: Functions for Managing the Keyboard Status 
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♦ Whether KbdCharln and KbdPeek report a keystroke when a shift 
key is pressed. 

♦ The turnaround character, which is the character that signals the 
end of user input to the KbdStringln function (the default key is 
Enter). 

♦ The state of the shift keys, such as Shift, Control, and Alt. 

Note that you must pass both of these functions a keyboard handle. 
However, setting these parameters for a given logical keyboard or for the 
physical keyboard (handle 0) simultaneously affects all other keyboards. 

Routine Replacement 

Table 9.14 lists the two functions for managing the replacement of Kbd 
functions. KbdRegister replaces one or more keyboard functions with rou¬ 
tines within a specified dynamic-link module, and KbdDeRegister restores 
all default keyboard routines. These functions work in the same manner as 
the equivalent video routines: VioRegister and VioDeRegister. See the 
explanation of these two routines in the section on replacing video func¬ 
tions, earlier in the chapter. 


Fyootlosi 

Purpose 

V 


KbdDeRegister 

Restores all default Kbd functions for the current screen 
group (that is, it cancels all keyboard function 
replacements made by KbdRegister). 

KbdRegister 

Replaces one or more Kbd functions with routines 
within a specified dynamic-link module. Replacement 
affects only the current screen group. 


TABLE 9.14: Functions for Routine Replacement 


Character Translation 

The functions for managing the translation of keystrokes into character 
values are listed in Table 9.15. The character code values returned by func¬ 
tions such as KbdCharln and KbdStringln are calculated based upon the 
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MOUSE 

FUNCTIONS 


Function 

V 

Purpose 

W 

KbdGetCp 

Obtains the identifier of the code page that is associated 
with the keyboard. 

KbdSetCp 

Sets the code page to be used to translate raw keystrokes 
into the character values returned by the keyboard input 


functions. 

KbdSetCustXt 

Installs a custom translation table to be used to convert 
all subsequent raw keystrokes into the character values 
returned by the keyboard input functions. 

KbdXlate 

Translates a specified keystroke scan code into a 
character value, using the current translation table. 


TABLE 9.15: Functions for Managing Character Translation 


scan code indicating the physical key pressed on the keyboard, the current 
state of the shift keys (such as Shift or Alt), and the current code page (or 
custom translation table) associated with the keyboard. 

The function KbdGetCp obtains the identifier of the current code page 
associated with the keyboard, and KbdSetCp allows you to set the code 
page. Note that the value must be one of those specified in the CODEPAGE 
configuration command, or the value 0, which represents the default code 
page. You can also call KbdSetCustXt to install a custom translation 
table—contained within your program—in lieu of one of the code pages 
installed in the system at configuration time. Finally, you can use KbdXlate 
to have the system translate a specific scan code into the appropriate charac¬ 
ter value, based upon the current code page or custom translation table and 
the state of the shift keys. 

See the OS/2 Programmer's Reference for the structure of a code page, 
and see the discussion on code pages in Chapter 8, under the section entitled 
National Language Support. 


The OS/2 functions for managing a mouse are contained in a dynamic-link 
module and are named with the Mou prefix. Unlike the screen and key¬ 
board modules, the mouse functions do not belong to the Family API; real 
mode programs must access the mouse driver through the interrupt 33h 
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interface. Note that programs using the Mou functions can run within a 
window of the Presentation Manager. 

Table 9.16 lists the functions belonging to the OS/2 mouse subsystem. 
The following is a typical sequence of steps for using the mouse from an 
application program: 

1. Open the mouse by calling MouOpen; you can specify the default 
mouse by passing a NULL (0) pointer for the device name (the 
first parameter). MouOpen returns a mouse handle that must be 
used for subsequent calls to the mouse functions. 

2. Call MouDrawPtr to display the mouse pointer on the screen. 
When you call this function, the system draws the mouse pointer 
at an initial screen position and automatically redraws the pointer 
at the appropriate location each time the user moves the mouse. 
Thus, your program does not have to manage saving and restoring 
the screen data and redrawing the mouse pointer. 

3. You can call MouRemovePtr to prevent writing screen data on top 
of the mouse pointer (which would obscure the pointer as well as 
erase your data when the system moves the pointer). You use this 
function to specify an exclusion rectangle; the mouse disappears if 
it moves into this rectangle, which can be as large as the entire 
screen. 

4. You can call MouDrawPtr to remove an exclusion rectangle cre¬ 
ated by MouRemovePtr, and to redraw the mouse if necessary. 

5. To find out what the mouse has been doing, you can call 
MouReadEventQue. Each time the user presses a mouse button or 
moves the mouse, the system places an entry in the mouse event 
queue\ which is structured on a first-in, first-out basis. By extract¬ 
ing elements from this queue, you can obtain a recent history of 
the mouse’s activities. Each element reports the specific mouse 
action and the location of the pointer on the screen when 

the action occurred. 

6. You can specify which mouse actions the system places in the event 
queue by calling MouSetEventMask. For example, your program 
may want to know only when the user presses the left mouse but¬ 
ton; this function allows you to eliminate irrelevant information 
from the event queue. 

7. You can also obtain the current screen coordinates of the mouse 
pointer by calling MouGetPtrPos, or place the pointer at a specific 
location by calling MouSetPtrPos. 
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8. When you are finished using the mouse, call MouClose to close the 
mouse device and release the handle. The mouse pointer is 
removed from the screen only after all processes within the current 
screen group have closed the mouse. 


Function 

V 

Purpose 

MouClose 

Closes the mouse device previously opened by 
the MouOpen function. 

MouDeRegister 

Restores all default Mou functions for the 
current screen group (that is, it cancels all 
mouse function replacements made by 
MouRegister). 

MouDrawPtr 

Causes the system to begin drawing the mouse 
pointer at the appropriate screen coordinates 
with each mouse interrupt. 

MouFlushQue 

Removes all events from the mouse event 
queue. 

MouGetDevStatus 

Reports the current status of the mouse device: 
whether the event queue is busy, whether a 
block read is in progress, whether a buffer is 
being flushed, whether the pointer-drawing 
function is enabled, and whether the mouse 
position is reported as absolute screen 
coordinates or as relative motion of the mouse 
in mickeys. 

MouGetEventMask 

Retrieves the current mouse event mask, which 
specifies the user actions that the system adds 
to the event queue each time they occur. 

Possible user actions are pressing a button, 
releasing a button, or moving the mouse. 

MouGetHotKey 

Reports the mouse hotkey that has been set by 
the system manager (if any). A hotkey is a 
combination of mouse buttons that is 
recognized by the system manager. 

MouGetNumButtons 

Reports the number of buttons on the mouse. 


TABLE 9.16: OS/2 Mouse Functions 
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Function 

V 

Purpose 

V 

MouGetMumMickeys 

Reports the number of mickeys per centimeter 
of mouse motion. A mickey is the 
measurement unit for mouse motion and the 
smallest distance that can be detected. 

MouGetNumQueEl 

Reports the number of events currently 
contained in the mouse event queue, and the 
maximum number of elements the queue can 
hold. 

MouGetPtrPos 

Reports the current row and column position 
of the mouse. 

MouGetPtrShape 

Retrieves the current bit masks used to draw 
the mouse pointer. 

MouGetScaleFact 

Reports the current horizontal and vertical 
scaling factors for mouse movement. A scaling 
factor is the number of mickeys the mouse 
must be moved to cause the mouse pointer to 
move one screen unit. 

MouInitReal 

Initializes the real mode mouse device driver; 
this function should be called only by the 
session manager and not by an application 
program. 

MouOpen 

Opens the mouse within the current screen 
group and returns a pointer that is used to 
identify the mouse when making subsequent 
calls to Mou functions. 

MouReadEventQue 

Retrieves the next mouse event from the event 
queue. The system adds an element to the 
queue each time the user presses or releases a 
button, or moves the mouse (provided the 
event is enabled through MouSetEventMask). 

MouRegister 

Replaces one or more Mou functions with 
routines within a specified dynamic-link 
module. Replacement affects only the current 
screen group. 


TABLE 9.16: OS/2 Mouse Functions (continued) 
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Function 

▼ 

Purpose 

▼ 

MouRemovePtr 

Defines an exclusion rectangle on the screen; 
the mouse pointer disappears each time it is 
moved into this area. 

MouSetDevStatus 

Enables or disables drawing of the mouse 
pointer, and specifies whether the mouse 
position is to be reported as absolute screen 
coordinates or as the relative motion of the 
mouse in mickeys. 

MouSetEventMask 

Specifies the user actions that the system adds 
to the mouse event qu eue each time they occur. 

You may specify one or more of the following 
user actions: pressing a button, releasing a 
button, or moving the mouse. 

MouSetHotKey 

Sets the system hotkey for the mouse; this 
function should be called only by the session 
manager. 

MouSetPtrPos 

Places the mouse pointer at the specified screen 
position. 

MouSetPtrShape 

Specifies the bit masks used to draw the mouse 
pointer. 

MouSetScaleFact 

Sets the current horizontal and vertical scaling 
factors for mouse movement. A scaling factor 
is the number of mickeys the mouse must be 
moved to cause the mouse pointer to move one 
screen unit. 

MouSynch 

Synchronizes access to the mouse driver to 
prevent more than one process from accessing 
the mouse at a given time. This function should 
be called only by a subsystem and not by an 
application program. 


TABLE 9.16: OS/2 Mouse Functions (continued) 
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Note that the mouse system allows you to replace specific Mou functions 
by calling MouRegister, or to restore the default functions by calling 
MouBeRegister. MouRegister and MouDeRegister work in the same fash¬ 
ion as the equivalent screen and keyboard functions. The mouse module 
also provides several functions for obtaining information on the mouse 
device, and for getting or setting the manner in which the mouse is moved 
and displayed. See Table 9.16 for a brief description of these functions, or 
the OS/2 Programmer's Reference for more details. 









































































































CHAPTER 


Developing 
and Using 
Dynamic-Link 
Libraries 

Chapter 2 summarized the key features of the OS/2 dynamic link¬ 
ing mechanism, emphasizing the differences between dynamic 
linking and static linking. This chapter describes the steps for develop¬ 
ing a dynamic-link library in the C language, and the procedures for 
calling functions within a dynamic-link library from a C program. 

From the viewpoint of the developer, writing a dynamic-link library 
is similar to writing a statically linked subroutine package; like a sub¬ 
routine, a function within a dynamic-link library runs as part of the 
calling process. Unlike a normal subroutine package, however, 
the dynamic-link code is contained in a separate file (with the .DLL 
extension) and typically maintains one or more of its own data seg¬ 
ments. Also, a single copy of the dynamic-link library in memory can 
be shared by several processes. Because of these differences, and due 
to the unique method for preparing a dynamic-link library, you must 
follow the special set of procedures described in this chapter. 
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This section illustrates the basic steps for writing a dynamic-link library 
in C, and presents the code for a simple dynamic-link subroutine li¬ 
brary It then introduces several advanced features of the OS/2 dynamic 
linking mechanism. 

The Basic Steps 

There are several different methods for writing dynamic-link libraries in the C 
language; the choice of method depends upon the features that are required. 
This section introduces the topic by presenting a basic method suitable for pro¬ 
ducing simple dynamic-link libraries. A dynamic-link library generated 
through these techniques is subject to the following limitations: 

♦ The library cannot contain an initialization routine. 

♦ The code cannot call standard C library functions. 

♦ The module contains only instance data segments (that is, a sepa¬ 
rate copy of the data segment is initialized for each client process). 

The section on Advanced Features, later in this chapter, describes how to 
circumvent each of these limitations and incorporate the corresponding fea¬ 
tures into your dynamic-link module. Note that the methods presented here 
apply specifically to the Microsoft C compiler. 

The following are the basic steps described in this section for writing a 
simple dynamic-link module in C: 

1. Write the C source file (.C) containing the dynamic-link functions. 

2. Compile the C source file to produce an object file (.OBJ). 

3. Write a definition file (.BEF) to export the dynamic-link func¬ 
tions. 

4. Pass the object file, together with the definition file, to the linker 
to produce a dynamic-link library file (.DLL). 

5. Process the definition file with the IMPLIB utility to generate an 
import library (.LIB file). 

These steps are illustrated in Figure 10.1. 

Figures 10.2 through 10.5 demonstrate this set of procedures. The files 
in these figures are used to build a simple dynamically linked module for 
displaying text mode windows and accepting data input from fields on 
the screen. 
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FIGURE 10.1: The basic steps for building a dynamic-link library 


Figure 10.2 

This listing provides an example of a dynamic-link module. It contains a 
set of routines for managing text mode windows and receiving data from 
fields on the screen. You can prepare the dynamic-link library file 
using the MAKE file of Figure 10.5. 

*/ 

#define INCL_SUB 

#include <os2.h> , 

#include "figlO 3.h" /* Prototypes for the dynamic-link module. */ 

int acrtused =0; /* Prevents linking of the C startup code. */ 


FIGURE 10.2: C source file for the dynamic-link screen management module 
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typedef struct 
{ 

unsigned StartRow; 
unsigned EndRow; 
unsigned Started; 
unsigned RowLength; 
> 

HEADER; 


/* Header for memory blocks used to store 
/* screen data. 

/* Dimensions of the block of saved screen 
/* data. 


/* TOTAL number of bytes in a row; 
/* times the number of characters. 


equals 2 


unsigned pascal far ScrSave (int UR, int LC, int LR, int RC, 

unsigned short far *PtrSelector) 

/* 

This function saves the rectangular block of screen data specified by the 
first 4 parameters % 'UR' (upper row), 'LC' (left column), 'LR' (lower 
row), and 'RC' (right column). It assigns a selector to 'PrtSelector' 
that can be passed to 'ScrRestore' to restore the saved block. 


{ 

unsigned Error; 
unsigned SegSize; 
unsigned RowLength; 
char far *PtrMem; 
HEADER far *PtrHeader; 
unsigned Row; 


/* Number of bytes in segment. 

/* Address to receive selector. 

/* Nonshareable, nondiscardable segment. 


/* Stores the API error code. */ 

/* Length of segment for storing a block. */ 
/* TOTAL number of bytes in a row of data.*/ 
/* For accessing screen data in segment. */ 
/* For accessing header in segment. */ 

/* Row index. */ 

/*** Allocate a segment from OS/2 to store the screen data. */ 

RowLength = (RC - LC + 1) * 2; 

SegSize = sizeof (HEADER) + RowLength * (LR - UR + 1); 

Error = DosAllocSeg 
(SegSize, 

PtrSelector, 

0 ) ? 

if (Error) 

return (Error); 

/*** Assign fields of segment header. ****************************************/ 
PtrHeader = MAKEP (*PtrSelector,0); ' 

PtrHeader->StartRow = UR; 

PtrHeader->EndRow = LR; 

PtrHeader->StartCol = LC; 

PtrHeader->RowLength = RowLength; 

/*** Copy screen data to segment. ********************************************/ 
PtrMem = MAKEP (*PtrSelector,sizeof (HEADER)); 
for (Row = UR;Row <= LR;++Row) 

{ 

VioReadCellStr (PtrMem,&RowLength,Row,LC,0); 

PtrMem += RowLength; 

} /* end for */ 
return (0); 

> /* end ScrSave */ 


unsigned pascal far ScrRestore (unsigned short Selector) 


/ 


This function restores a block of screen data previously saved by the 
ScrSave function (you must pass the selector returned by ScrSave). 

{ 


FIGURE 10.2: C source file for the dynamic-link screen management module (continued) 
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unsigned Error; /* Stores the API error code. */ 

char far *PtrMem; /* For accessing screen data in segment. */ 

HEADER far *PtrHeader; /* For accessing header in segment. */ 

unsigned Row; /* Row index. */ 

/*** Initialize pointers. ****************************************************/ 
PtrHeader = MAKEP (Selector,0); /* Pointer to header. */ 

PtrMem = MAKEP (Selector,sizeof (HEADER)); /* Pointer to screen data. */ 

/*** copy the data from the memory segment to the screen. ********************/ 
for (Row=PtrHeader->StartRow;Row<=PtrHeader->EndRow;++Row) 

VioWrtCellStr (PtrMem,PtrHeader->RowLength,Row,PtrHeader->StartCol,0); 
PtrMem += PtrHeader->RowLength; 

} /* end for */ 

DosFreeSeg (Selector); /* Free the segment. */ 

return (0); 

} /* end ScrRestore */ 


unsigned pascal far ScrDrawBox (int UR, int LC, int LR, int RC, int Style, 

int ClearFlag) 

/* 

This function displays a box on the screen starting at row and column 
'UR' and 'LC' and ending at row and column 'LR' and 1 RC’. 'Style' 
selects the line style, and may be between 0 and 3. If 'ClearFlag' is 
set to a nonzero value, the function will clear the area inside the box. 

*/ 

/* Stores the box-drawing characters for each style. */ 

static char ulc [] = {218,201,213,214}; 

static char urc [] = {191,187,184,183}; 

static char 11c [] = {192,200,212,211}; 

static char lrc [] = {217,188,190,189}; 

static char hi [] = {196,205,205,196}; 

static char vl [] = {179,186,179,186}; 

register int Row, Col; 

/*** Clear the screen if requested. ****************************************^ 
if (ClearFlag) 

VioScrollUp (UR,LC,LR,RC,Oxffff," \x07",0); 




VioWrtNChar (ulc+Style,1,UR,LC,0); 
VioWrtNChar (hl+Style,RC-LC-l,UR,LC+1,0); 
VioWrtNChar (urc+Style,1,UR,RC,0); 
for (Row=UR+l;Row<LR;++Row) 

{ 

VioWrtNChar (vl+Style,1,Row,LC,0); 
VioWrtNChar (vl+Style,1,Row,RC,0); 

} /* end for */ 

VioWrtNChar (llc+Style,1,LR,LC,0); 
VioWrtNChar (hl+Style,RC-LC-1,LR,LC+1,0); 
VioWrtNChar (lrc+Style,1,LR,RC,0); 
return (0); 


} /* end ScrDrawBox */ 
static int _ToUpper (int Char); 


*7 

/* Upper left corner. */ 
/* Top side. */ 
/* Upper right corner. */ 
/* Vertical sides. */ 


/* Lower left corner. */ 
/* Bottom side. */ 
/* Lower right corner. */ 


/* Local function. 


HQURE 10.2: C source file for the dynamic-link screen management module (continued) 
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mt pascal far ScrGetString (char far *Buffer,int Attr,int Row,int Col, 

int Length, int Mode) 

/* 

This function reads characters into 'Buffer', echoing the input starting 
at Row and 'Col', using video attribute 'Attr'. Characters are 
read until an exit key (CR, Esc, or arrow) is encountered, or until the 
number read is one less than the specified buffer size. Length. If 
the first key pressed is an exit key, the buffer is unaltered. 

Otherwise, the buffer is initially filled with blanks and terminated 

a n ^i 1? therefore , the resulting string will be blank-padded on the 
right. The terminating exit key is not placed into the buffer. The 
'Length' parameter should equal the 'sizeof' the receiving buffer. 

The 'Mode' parameter can specify one or more of the following features 
(constants are defined in FIG10_3.H): 

NOFEAT: No 'Mode' features specified. 

AUTOEXIT: Exit field automatically when buffer is full. 

UPPER: Convert all letters to uppercase. 

The function returns one of the following codes indicating the field 
exit key pressed by the user: 

-1 <Esc> 

0 <CR> 

1 <Left-Arrow> 

2 <Right-Arrow> 

3 <Up-Arrow> 

4 <Down-Arrow> 

5 Automatic exit (last character entered and AUTOEXIT selected). 


KBDKEYINFO Key; 
int Keystroke; 
char Cell [2]; 
register int CurCol,i; 
int FirstChar =1; 
char far *PtrCh; 

CurCol = Col; 

VioSetCurPos (Row,CurCoL,0) 
Cell [1] = (char)At t r; 

for (;;) 

{ 

KbdCharln (&Key,0,0); 
Keystroke = (Key.chScan << 
switch (Keystroke) 

{ 

case 0x011b: 

return (-1); 
case 0x4b00: 

return (1); 
case 0x4d00: 

return (2); 
case 0x4800: 

return (3); 
case 0x5000: 

return (4); 


/* Buffer to receive keystrokes. */ 

/* Stores scan code and character value. */ 

/* Holds a character/attribute pair. */ 

/* Current column/loop index. */ 

/* Flag to indicate the first character. */ 

/* For filling buffer with blanks. */ 

/* Initialize current column. */ 

; /* Place cursor at first position. */ 

/* Assign the attribute to the cell. */ 

/* Keyboard read loop. */ 

/* Read a character from the keyboard. */ 

8) | Key.chChar; 

/* Branch according to the scan code */ 

/* and character value. *7 

/* Escape. *j 

/* Left arrow. *j 

/* Right arrow. * j 

/* Up arrow. */ 

/* Down arrow. */ 


FIGURE 10.2: C source file for the dynamic-link screen management module (continued) 
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case OxlcOd i /* Return, 

return (0); 

case 0x0e08: /* Backspace, 

if (CurCol > Col) 

{ 

VioSetCurPos (Row,—CurCol,0); 

Cell [0] = ' 

VioWrtNCell (Cell,1,Row,CurCol,0); 
*—Buffer = ' '; 


*/ 

*/ 


/* Move cursor back. */ 
/* Write blank to */ 
/* screen and buffer.*/ 


} 

break; 

defaults /* Either a normal character or a non-ASCII value. */ 

if (CurCol >= Col + Length - 1) /* Test end of buffer. */ 

break; 

if (Key.chChar == 0) /* Test for non-ASCII character*/ 

break; 

if (Mode & UPPER) /* Uppercase conversion. */ 

Key.chChar = (char)_ToUpper (Key.chChar); 


/* A normal character; write it to the screen & buffer. */ 

Cell [0] = Key.chChar; 

VioWrtNCell (Cell,1,Row,CurCol,0); 

VioSetCurPos (Row,++CurCol,0); 

*Buffer++ = Key.chChar; 

if (FirstChar) /* Blank-fill buffer on first character. */ 

{ 

FirstChar = 0; 

Cell [0] = ' '; 

VioWrtNCell (Cell,Length-2,Row,CurCol,0); 

PtrCh = Buffer; 

for (i=l;i<=Length-2;++i) 

*PtrCh++ = ' '; 

*PtrCh = '\0'; 

^ /* Test for autoexit. */ 

if ((CurCol >= Col + Length - 1) && (Mode & AUTOEXIT)) 

return (5); /* Code for autoexit. */ 

break; 


} /* end switch */ 

} /* end for */ 

} /* end ScrGetString */ 


static int _ToUpper (int Char) 

/* 

This function converts a lowercase character to an uppercase character. 
If the character is not a lowercase alphabetical character, it is not 
altered. 

*/ 

{ 

if (Char >= 'a' && Char <= 'z') 
return (Char - 32); 

else 

return (Char); 

> /* end _ToUpper */ 


FIGURE 10.2: C source file for the dynamic-link screen management module (continued) 
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/* 

Figure 10.3 

This header file should be included in any program that calls the 
dynamic-link library functions of Figure 10.2. See Figure 10.2 for 
a description of the parameters. 


unsigned pascal far ScrSave 
(int UR, 
int LC, 
int LR, 
int RC, 

unsigned short far *PtrSelector); 

unsigned pascal far ScrRestore 
(unsigned short Selector); 

unsigned pascal far ScrDrawBox 
(int UR, 
int LC, 
int LR, 
int RC, 
int Style, 
int ClearFlag); 

int pascal far ScrGetString 
(char far *Buffer, 
int Attr, 
int Row, 
int Col, 
int Length, 
int Mode); 

#define NOFEAT 0x0000 

#define AUTOEXIT 0x0001 

#define UPPER 0x0002 


FIGURE 10.3: Header file for the dynamic-link screen management module 


; Figure 10.4 

; This linker.definition file should be used when linking the dynamic-link 
; module of Figure 10.2, or when preparing an import library for this module 
? with the IMPLIB utility. 

;Creates and names a dynamic-link library. 

LIBRARY FIG10_2 

;Causes a separate copy of the default data segment to be loaded and 
;initialized for each instance of the dynamic-link library. 

DATA NONSHARED 

;Lists the functions that may be called by a client process. 

EXPORTS 

SCRSAVE 

SCRRESTORE 

SCRDRAWBOX 

SCRGETSTRING 


/* Constants for ScrGetString 'Mode' parm. */ 
/* Turn off all ’mode’ features. */ 
/* Exit field automatically on full buffer. */ 
/* Convert all letters to uppercase. */ 


FIGURE 10.4: Definition file for the dynamic-link screen management module 
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# Figure 10.5 -.no 

# This MAKE file is used to prepare the dynamic-link module of Figure lu. Z 

# 

figlO 2.obj : figl0_2.c figl0_3.h 

cl /W2 /c /Asnu /Gs2 /Zp figl0_2.c 

figl0_2.dll : figl0_2.obj figl0_4.def . . . , 

link /NOD /NOI figl0_2.obj / figl0_2.dll, NUL, doscalls.lib, figl0_4.def 

figl0_2.lib s figl0_2.dll figl0_4.def 
irnplib figl0_2.1ib figl0_4.def 


FIGURE 10.5: MAKE file for the dynamic-link screen management module 


Write the Source File 

In general, a module of C functions destined to be converted to a dynamic- 
link library can be written in the same manner as a statically linked subrou¬ 
tine package. However, if you are using the method described in this 
section, you must abide by the following special guidelines. 

First, you should place the following line at the beginning of the source 
file (outside of a function definition): 

int_acrtused = 0; 

This mysterious variable definition resolves references to the variable 
acrtused, employed by the C startup routines, and thereby prevents the 
standard C startup code from being linked into the module. The startup 
code is not needed by a dynamic-link module that does not call C library 
functions. 

Second, you must not call functions in the standard C library. These 
functions have not been properly written and compiled so that they can be 
executed from dynamic-link modules. Although this is a grave limitation 
for writing complex functions, you are free to call any of the OS/2 API 
functions. Also, the section on Advanced Features (later in the chapter) 
describes a special version of the C library provided with Microsoft C 5.1 
that may be called by dynamic-link code. 

Third, when writing a dynamic-link library, you should strive to make 
your code reentrant, since these modules are typically shared. A dynamic- 
link library can be shared both by separate processes and by separate 
threads within a single process. Although multiple processes share a single 
copy of the dynamic-link library code segment, if you follow the steps 
described here, each process has its own copy of the data segment. (These 
are known as instance data segments; global data segments, which are 
shared by all client processes, are described in the section on Advanced Fea¬ 
tures). Therefore, if more than one process executes the same section of 
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code within a dynamic-link library, each process has its own copy of all data 
variables and no conflicts can arise. 

If, however, more than one thread within a single process calls the same 
dynamic-link library, these threads share all external and static data. 
Although the data segment is shared among threads, each thread owns its 
own stack and the dynamic-link code uses the stack that belongs to the call¬ 
ing thread. Therefore, you can provide separate copies of data variables for 
each thread by placing these variables within the stack. See the section in 
Chapter 6 on Using Multiple Threads for more information on writing 
reentrant C code. 

Finally, when a process calls a dynamic-link library function, the func¬ 
tion executes as part of the calling process. (The type of dynamic-link 
functions you write are invoked by simple far call instructions, and no task 
switches take place.) The dynamic-link library thus has immediate access to 
all resources, such as file handles and memory segments, that are owned by 
the calling process. Therefore, when writing dynamic-link code you must be 
careful not to create side effects—by manipulating these resources—that 
are harmful to the client process. For example, you should neither arbitrar¬ 
ily close all file handles, nor use an excessive number of file handles (which 
might leave the client processes with too few handles; if the dynamic-link 
module needs additional handles, it should first call DosSetMaxFH to 
increase the maximum number of handles). 

Note that if a dynamic-link library needs to maintain a stable set of 
resources that are distinct from those owned by its client processes, it can 
start a separate process to allocate and manage these resources. The new 
process should be executed as a detached background task so that it cannot 
be killed or waited on by any of the clients. The dynamic-link module can 
subsequently communicate with the new process through an appropriate 
form of interprocess communication. 

The C source code for the example dynamic-link library is located in Fig¬ 
ure 10.2. Note that this module follows the rules outlined above and is thus 
capable of being dynamically linked. The module contains four functions 
that can be used in concert for displaying windows and accepting input 
from data entry screens. These functions allow you to perform the follow¬ 
ing typical sequence of tasks: 

1. You can call ScrSave to save a rectangular section of the screen. 
ScrSave supplies a selector that can later be used to restore this 
data to the screen. 

2. Once the screen data are saved, you can call ScrDrawBox to draw a 
border around the saved area (you should pass the same row and 
column dimensions to ScrSave and ScrDrawBox). When calling 
ScrDrawBox, you can optionally clear the area inside of this window. 
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3. You can write messages and other data to specific positions within 
the window by calling a standard OS/2 function such as VioWrt- 
CharStr. 

4. You can call ScrGetString to read a string from the keyboard, 
echoing the characters to a specified position on the screen with a 
given display attribute. Note that unlike KbdStringln, this func¬ 
tion strictly confines echoed output to the specified area. The user 
can end input by pressing Return, Escape, or an arrow key; the 
function returns a code indicating which key was pressed. You can 
also request either automatic conversion to uppercase letters, or 
automatic field exit after a character is entered into the last field 
position. 

5. When you have finished using the window, you can call ScrRestore 
to remove the window and restore the original screen data. You 
must pass ScrRestore the selector that was returned by ScrSave to 
identify the specific block of saved screen data. 

6. Since you can save multiple screen areas and restore them at any 
time and in any order, these functions can be used to manage mul¬ 
tiple stacked windows. 

Note that ScrSave saves all characters and display attributes from the 
specified area of the screen by calling VioReadCellStr for each row, and 
ScrRestore restores this data by calling VioWriteCellStr. Each time ScrSave 
is called, it invokes DosAllocSeg to dynamically allocate a block of memory 
to store the screen data; when ScrRestore subsequently restores this data, it 
calls DosFreeSeg to release the segment. The segment used to store the 
screen data is also used to store the row and column parameters associated 
with this data, and the segment selector is returned to the calling program. 
The calling program thus needs to store only the selector and is not required 
to keep any additional information regarding the saved screen area. The 
functions ScrDrawBox and ScrGetString likewise use the standard OS/2 
Vio and Kbd functions. 

Note also that the naming conventions used for these functions follow 
the same format as that used for the OS/2 functions; since a dynamic-link 
library forms an extension of the operating system itself, it makes sense to 
follow the same conventions. Also, the names are descriptive, and the pre¬ 
fix ( Scr ) does not conflict with any prefixes used by OS/2 (such as Vio or 
Win). The use of these functions is demonstrated in Figures 10.6 and 10.7, 
described later in the chapter. 
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Compile the Source File 

The next step in creating a dynamic-link library is to compile the source 
code, using an appropriate set of options. To compile a dynamic-link mod¬ 
ule, you should invoke the CL command with the following command-line 
options (in addition to any other options you need to specify): 

EFFECT 

Forces the compiler to use small (16-bit) code pointers. 

Forces the compiler to use near (16-bit) data pointers. 

Causes the compiler to save the contents of the DS register on 
function entry, to set DS to the selector for the data segment 
belonging to the current module, and to restore the original DS 
value before function exit. Note that when this option is 
specified, the compiler will not assume that the DS register is 
equal to the SS register (which is the default condition). 

Eliminates calls to the stack-checking routine that are 
otherwise made at the beginning of each function. 

As an example, the following command line would compile the source 
file of Figure 10.2, producing an object file suitable for generating a 
dynamic-link library: 

cl /c /Asnu /Gs2 /Zp figl 0_2.c 

Note that this command is the same as that employed by the MAKE file 
of Figure 10.5. The /Au switch is necessary because the dynamic-link mod¬ 
ule is contained in a separate executable file and uses a separate data seg¬ 
ment from that belonging to the main program. (When a subroutine 
module is statically linked to a C program, it normally uses the same data 
segment as the main program for all external and statically defined vari¬ 
ables.) Therefore, when a dynamic-link function is called, it is necessary 
to preserve the existing contents of the data segment (DS) register and to 
reload this register with the selector for the new segment. Also, since the 
stack is not switched when entering a dynamic-link function, the contents of 
the stack segment (SS) register are no longer equal to the contents of the 
data segment register (normally, SS is equal to DS); the /Au switch prevents 
the compiler from assuming that these two registers are equal within the 
scope of the dynamic-link module. 

Note that because a dynamic-link function uses a separate data segment 
from that belonging to the main program, all addresses passed as parame¬ 
ters must be far addresses. If a near address (which specifies only the offset) 
were passed to a dynamic-link function, the program would attempt to 


CL OPTION 

/As 

/An 

/Au 


/Gs 
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address a variable contained in the data segment of the main program using 
the selector for the data segment belonging to the dynamic-link module; a 
general-protection fault would most likely result. 

You should specify the /Gs option to disable the calls normally made to 
the standard C stack-checking routine at the beginning of each function. 
The stack-checking routine makes sure that there is sufficient stack space to 
execute the subroutine; however, because of the different segment setup for 
a dynamic-link module, this routine would cause unpredictable results. 


Write the Definition File 

Before linking a dynamic-link module, you must prepare a definition file 
(.DEF) to tell the linker which functions within this module are to be 
exported. Exported functions are those that may be called by a client pro¬ 
gram at run-time; the offset of each exported function is added to the list of 
entry points within the header of the .DLL file. 

You must include the following statements in the definition file: 

♦ The LIBRARY statement, which causes the linker to generate a 
dynamic-link library file (.DLL) rather than a normal executable 
file (.EXE). This statement must be followed by the name of the 
dynamic-link module (do not include the .DLL extension). 

♦ A DATA NONSHARED statement, so that a separate copy of the 
data segment is loaded and initialized for each client process that 
accesses the module. 

♦ An EXPORTS statement, listing all functions within the dynamic- 
link module that can be called by a client program. 

Figure 10.4 provides a definition file for the dynamic-link module of 
Figure 10.2. Note that even though the names of the dynamic-link functions 
as they are defined and called are written in uppercase and lowercase letters, 
they are listed as all uppercase letters in the definition file; this convention is 
necessary because these functions are declared using the pascal keyword, 
which causes the compiler to convert these names to uppercase before they 
are inserted in the object file. The name in the definition file must exactly 
match the name in the object file. (If the functions were not declared using 
the pascal keyword, the compiler would preserve the case but append an 
underscore to the beginning of each name; you would have to use the same 
convention when listing such functions in the definition file.) 

Module definition files are described in Chapter 4, and the commands 
you can place in these files are listed in Appendix D. 
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Link the Library 

The next step is to use the linker to convert the object file (.OBJ) to a 
dynamic-link library file (.DLL). The procedure is similar to that used to 
generate standard executable files, with the following exceptions: 

♦ You should not have the linker search the standard C library. Do 
not include the name of the C library on the command line, and 
use the /NOD option to stop the linker from searching the default 
libraries. 

♦ Specify the definition file described in the previous section as the 
last parameter on the command line. 

Note also that you must use a version of the linker designed to produce 
OS/2 protected mode programs and dynamic-link library files. As an 
example, the following command line can be used to prepare the dynamic- 
link library for the module listed in Figure 10.2: 

link/NOD /NOI fig10_2.obj, fig10_2.dll, NUL, doscalls.lib, 

fig10_4.def 

Note that this is the same command issued from the MAKE file of Figure 10.5. 

Generate m Import Library 

The final step is to use the IMPLIB utility to prepare an import library. As 
described in Chapter 2 (in the section on Dynamic Linking), an import 
library can be used when linking an application that calls functions within a 
dynamic-link library. As you have seen many times in this book, DOS¬ 
CALLS.LIB is the import library for resolving references to the OS/2 
dynamic-link functions; you can also prepare an import library for your 
own dynamic-link module. 

Note that preparing and using an import library is optional. If an import 
library is not available, you must provide a definition file when linking any 
program that calls one or more of your dynamic-link functions (this file 
must explicitly list each dynamic-link function it calls in an IMPORTS 
statement). If you have prepared an import library, you can simply add this 
library to the list of search libraries on the linker command line. The import 
library will allow the linker to resolve all references to functions within your 
dynamic-link module, without the need for a definition file. (As mentioned 
in Chapter 2, such an import library contains no function code, but only 
records that specify the name of the dynamic-link module and the entry 
point within this module for each function.) See the section on Using 
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Dynamic-Link Libraries, later in this chapter, for an example of using an 
import library 

An import library is prepared directly from a definition file by using the 
OS/2 IMPLIB utility (Note that the actual dynamic-link library is not 
involved in this process.) The following command line (which also appears 
in the MAKE file of Figure 10.5) can be used to prepare an import library 
for the dynamic-link module of Figure 10.2: 

implib figl 0_2 .lib figl 0_4.def 

Advanced Features 

A dynamic-link library prepared according to the method given thus far is 
subject to several limitations, which were summarized in the introduction to 
the first section of this chapter. This section introduces techniques for over¬ 
coming these limitations. A lengthy discussion of these methods, however, 
is beyond the scope of this book. See the printed manuals, “readme” files, 
and example programs supplied with your compiler for further details. 

Initialization and Termination Routines 

A dynamic-link library prepared according to the basic method described in 
this chapter receives control only when a client process explicitly calls a 
function within this library. However, you can also write an initialization 
routine that automatically receives control when a client process first 
accesses the dynamic-link module, and a termination routine that is exe¬ 
cuted when a client process exits. 

With the current version of the Microsoft C compiler (5.1), a dynamic- 
link initialization routine must be written in assembly language. (This rou¬ 
tine, however, can simply call a function written in C that contains the 
actual initialization code.) The assembly language module containing 
the initialization routine must have an END statement, which specifies the 
entry point that is to receive initial control. For example, the following is a 
fragment of an assembly language module that defines an initialization rou¬ 
tine; this routine receives initial control, calls a C function that contains the 
actual initialization code, and returns to the system. 

_TEXT SEGMENT BYTE PUBLIC ’CODE’ 

INIT PROC FAR 

CALL CJNIT ;lnvokes the actual initialization 

function, written in C. 

RET ;Far return to the system. 

INIT ENDP 

_TEXT ENDS 

END INIT 


;Defines the initialization entry point. 
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When you iink an initialization module to the dynamic-link library, you 
can specify an additional keyword after the LIBRARY statement and the 
module name in the definition file. The INITGLOBAL keyword causes the 
system to invoke the initialization routine only when the dynamic-link mod¬ 
ule is first loaded into memory; the following is an example: 

LIBRARY MOD__NAME INITGLOBAL 

The INITINSTANCE keyword, however, causes the system to invoke the 
initialization routine each time a new client process gains access to the 
dynamic-link module; this option is illustrated in the following line: 

LIBRARY MODJMAME INITINSTANCE 

If you do not specify either of these keywords, the INITGLOBAL option is 
in effect by default and the initialization routine is called only once. 

Note that before an initialization routine returns, it should set register 
AX to 0 if the routine was successful, and to a nonzero value if an error 
occurred. In the assembly language example above, the AX register is set by 
the C function that it calls, since the return value from a C function is 
placed in the AX register. 

Initialization routines are especially useful for dynamic-link subsystems 
that manage a resource and must make preparations before processing indi¬ 
vidual client requests. 

You can also install a routine that receives control when a client process 
terminates. If your dynamic-link module needs to perform some final tasks 
whenever a client process has finished using the module, you should not 
trust this process to voluntarily call an exit routine, since the process may 
terminate abnormally. Rather, you should install a termination routine 
using the DosExitList function. Such a routine will be called regardless of 
how the client terminates (this routine is called in addition to any termina¬ 
tion functions installed by the client itself). Note that the dynamic-link 
module must call DosExitList for each client process (while executing 
within the context of that process). 


Using Instance and Global Segments 

If you prepare a dynamic-link library according to the instructions given in 
the first section of this chapter, a separate copy of the default data segment 
is automatically loaded and initialized for each client process; such a seg¬ 
ment is known as an instance data segment. A dynamic-link library can also 
allocate a single data segment that is shared by all client processes; this type 
of segment is known as a global data segment. Global data segments are 
especially useful for writing subsystems, which must typically maintain 
global information that is accessible when serving any client process. 
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You can specify whether the default data segment is to be shared through 
the DATA statement of the definition file. The statement 

DATA MULTIPLE 
or 

DATA NONSHARED 

makes the default data segment an instance segment. The statement 
DATA SINGLE 
or 

DATA SHARED 

makes the default data segment a global segment. You can also create a 
dynamic-link module that has both an instance data segment and a global 
data segment (or several of each). You can create a separate data segment 
for each C source file by using the /ND compiler option; you can then 
specify whether an individual named data segment is an instance or global 
segment by using the SEGMENTS definition file command. (When you 
name a data segment with the /ND option, the compiler sets up several 
additional null segments that bear this same name as a prefix; these seg¬ 
ments must also be specified under the SEGMENTS command, in the same 
order they are placed in memory. You can refer to a linker map for the exact 
segment names and linking order; see also the compiler documentation and 
“readme” files for details.) 

Note that when you are using shared data segments, you must consider 
the issues of writing reentrant code and protecting shared data structures. 
See the section in Chapter 6 on Using Multiple Threads for more informa¬ 
tion on this topic. 

Using the C Library 

As mentioned in the last section, you cannot call standard C library func¬ 
tions from a dynamic-link module. Microsoft C (version 5.1), however, 
now provides two special versions of the C run-time library that can be 
called from dynamic-link functions. 

One of these libraries contains functions that can be called by only one 
thread at a time (in other words, these functions are nonreentrant). If you use 
this library, then all client processes must be single-thread applications (or must 
somehow avoid calling the dynamic-link library through more than one thread 
at a given time). Alternatively, the dynamic-link library itself can use sema¬ 
phores to serialize all calls to C library functions; in this case, a multiple-thread 
client process can freely use the dynamic-link library. 
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The other special version of the library contains reentrant functions, and 
can therefore be called by more than one thread at a given time. This version of 
the library is designed to be converted into a dynamic-link library itself, and 
can be called either by application programs or by dynamic-link modules. 

If you use either of these two C libraries, you must prepare your dynamic- 
link module using a different set of procedures than those described thus far. 
Consult the manuals, the “readme 55 files, and the example programs that come 
with your compiler for the names of all files and detailed instructions for using 
these libraries. 


As described in the section in Chapter 1 on Dynamic Linking, the system 
can perform dynamic linking either at load-time or at run-time. 

Load-time dynamic linking is the more commonplace and the simpler of 
the two methods. If are using load-time dynamic linking, your program can 
call functions in a dynamic-link library in the same manner that it calls C 
library functions or other statically linked subroutines. When you link such 
a program, these calls are resolved by records in an import library (or 
optionally through an IMPORTS statement in a definition file). At load¬ 
time, the operating system automatically loads the required dynamic-link 
module (if it has not already been loaded), and gives all calls to dynamic- 
link functions the immediate far addresses of the function entry points in 
memory. 

The example program in Figure 10.6 calls functions in the module of Fig¬ 
ure 10.2, and dynamically links with this module at load-time. This pro¬ 
gram can be prepared through the following command line: 

cl /G2 /Zp /Lp figl 0_6.c figl 0_2.lib 

Note that this command causes the linker to search not only the protected 
mode C run-time library and the OS/2 API library, but also the import 
library prepared for the screen management module (FIG10_2.LIB). The 
example program uses the screen management functions listed in Figure 
10.2 to display and remove three stacked windows, and to accept a string 
from a field within one of the windows. 

If you are using run-time dynamic linking, your program must make 
explicit OS/2 API function calls to load the module and obtain the address 
of each dynamic-link function. The following is the sequence of steps 
required to perform run-time dynamic linking: 

1. Call DosLoadModule to load the dynamic-link module into mem¬ 
ory (if it is not already loaded) and to obtain a handle for this 
module. 
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/* 

Figure 10.6 

This program is dynamically linked at load-time with the module of Figure 
10.2. It uses the functions in this module to display and remove three 
overlapping windows on the screen, and to read a string from a field 
within one of the windows. You can prepare this program using the 
following command lines 

cl /G2 /Zp /Lp figl0_6.c figl0_2.1ib 


*/ 

♦define INCL_BASE 
#include <os2.h> 

#include "figl0_3.h" /* Contains definitions for the dynamic-link module. */ 


#define NUMWINDOWS 3 

unsigned short SelectorTable [NUMWINDOWS]; 
void main () 


/* Number of windows displayed.*/ 
/* Stores the selectors for */ 
/* saved screen data blocks. */ 


/*** 


< 

int i = 0; 
int ULR, ULC; 

KBDKEYINFO Key; 
unsigned OldRow,OldCol; 
char Buffer [11]; 
unsigned ProcessID; 

Save the old cursor position. 
VioGetCurPos (SOldRow,&01dCol, 


/* Index to 'SelectorTable'. */ 

/* Upper left row / upper left column. */ 

/* Buffer to store keystroke information.*/ 

/* Old cursor position. */ 

/* Receives input string. */ 

/* Used by DosCWait. */ 

******************************************/ 

0 ); 


/*** Display window 1. ******************************************************/ 
ULR = ULC = 0; 

ScrSave (ULR,ULC,ULR+11,ULC+39,^SelectorTable [i++]); 

ScrDrawBox (ULR,ULC,ULR+ll,ULC+39,0,1); 

VioWrtCharStr ("WINDOW ON E",19,ULR+3,ULC+9,0); 

VioWrtCharStr ("Press any key to continue ...",29,ULR+6,ULC+4,0); 
VioSetCurPos (ULR+6,ULC+34,0); 

KbdCharln (&Key,0,0); 


/*** Display window 2. ******************************************************/ 
ULR += 2; 

ULC += 4; 

ScrSave (ULR,ULC,ULR+11,ULC+39,SSelectorTable [i++]); 

ScrDrawBox (ULR,ULC,ULR+11,ULC+39,1,1); 

VioWrtCharStr ("WINDOW T W 0",19,ULR+3,ULC+9,0); 

VioWrtCharStr ("Press any key to continue ...",29,ULR+6,ULC+4,0); 
VioSetCurPos (ULR+6,ULC+34,0); 

KbdCharln (&Key,0,0); 

/*** Display window 3. ******************************************************/ 
ULR += 2; 

ULC += 4; 

ScrSave (ULR,ULC,ULR+11,ULC+39,SSelectorTable [i++]); 

ScrDrawBox (ULR,ULC,ULR+11,ULC+39,2,1); 

VioWrtCharStr ("WINDOW THRE E",2 3,ULR+2,ULC+8,0); 

VioWrtCharStr ("Enter your names", 16,ULR+6,ULC+4,0); 

VioWrtNCell (" \x70",10,ULR+6,ULC+22,0); 

ScrGetString (Buffer,0x70,ULR+6,ULC+22,sizeof (Buffer),NOFEAT); 

/*** Remove window 3. *******************************************************/ 
ULR-=2; 


FIGURE 10.6: A program demonstrating load-time dynamic linking 
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ULC-=4; 

ScrRestore (SelectorTable [--!]); 

VioSetCurPos (ULR+6,ULC+33,0); 

KbdCharln (StKey-,0,0); 

/*** Remove window 2. ***************************************************★***/ 
ULR-=2; 

ULC-=4; 

ScrRestore (SelectorTable [—i]); 

VioSetCurPos (ULR+6,ULC+33,0); 

KbdCharln (&Key,0,0); 

/*** Remove window 1. *******************************************************j 
ScrRestore (SelectorTable [—i]); 

/*** Restore original cursor position. **************************************/ 
VioSetCurPos (01dRow,01dCol,0); 

} /* end main */ 


FIGURE 10.6: A program demonstrating load-time dynamic linking (continued) 


2. Call DosGetProcAddr to obtain the far address of the desired 
function. This address can be stored in a far function pointer. 

3. Invoke the dynamic-link function by using the indirection opera¬ 
tion on the function pointer and supplying the appropriate param¬ 
eters. 

4. Obtain and call any other required dynamic-link functions using 
the same method. 

5. When you no longer require the module, call DosFreeModule; the 
system will release the module after all client processes have called 
this function. 

The example program in Figure 10.7 uses run-time dynamic linking to 
call several of the screen management functions of Figure 10.2. This 
program simply displays a window, pauses for the user to press a key, and 
then restores the screen. You can see from this listing that the coding for 
run-time dynamic linking is considerably more complex than that for load¬ 
time dynamic linking. Also, when using function pointers rather than 
simple function calls, the compiler cannot perform its normal parameter 
type checking. However, run-time dynamic linking could be advantageous 
for linking dynamic-link modules that are used infrequently. Also, a pro¬ 
gram may need to load only one of several alternative modules; run-time 
dynamic linking could be used to prevent the system from arbitrarily load¬ 
ing unnecessary modules. 
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/* 

Figure 10.7 

This program is dynamically linked at run-time with the module of Figure 
10.2, and uses the functions in this module to display and remove a 
window on the screen. You can prepare this program using the 
following command lines 


cl /G2 /Zp /Lp figl0_7.c 

*/ 

#define INCL_D0S 
#define INCL_SUB 

♦include <os2.h> . , . 

♦include 11 figl0_3 .h M /* Contains definitions for the dynamic-link module. */ 

♦include <stdio.h> 

♦include <process.h> 


♦define ULR 6 
♦define ULC 20 


/* Coordinates of the upper left corner of the */ 

/* window displayed on the screen. */ 


void main () 

{ 

unsigned Error; 
char FailName [13]; 
unsigned int ModuleHandle; 
int (pascal far *ProcAddr)(); 
unsigned short Selector; 
unsigned 01dRow,01dCol; 
KBDKEYINFO Key; 

/*** Save the old cursor position. ** 
VioGetCurPos (SOldRow,SOldCol,0) 


/* Stores the API error code. */ 
/* Used by DosLoadModule. */ 
/* Handle to dynamic-link module. */ 
/* Pointer to dynamic-link functions.*/ 
/* Selector for stored screen data. */ 
/* Old cursor position. */ 
/* Buffer to hold keystroke info. */ 

***************************************/ 


/*** Load the dynamic-link module. ******************************************/ 
Error = DosLoadModule 

(FailName, /* Receives name of file causing failure. */ 

sizeof (FailName), /* Length of 'FailName' buffer. */ 

"FIG10 2", /* Name of dynamic-link module. */ 

&ModuleHandle); /* Receives handle to dynamic-link module. */ 

if (Error) 

fprintf (stderr,"Error %d calling DosLoadModule; Module %s\n", 

Error,FailName); 

exit (1); 

> 

/*** Get address of ScrSave function. ***************************************/ 
DosGetProcAddr 

(ModuleHandle, /* Dynamic-link module handle. */ 

"SCRSAVE", /* Name of dynamic-link function. */ 

&ProcAddr); /* Receives address of dynamic-link function. */ 

/*** Call ScrSave through the function pointer. *****************************/ 
(*ProcAddr) (ULR,ULC,ULR+11,ULC+39,(unsigned short far *)&Selector); 


/*** Get address of ScrDrawBox function. 
DosGetProcAddr 

(ModuleHandle, 

"SCRDRAWBOX", 

&ProcAddr); 




FIOUBE 10.7: A program demonstrating run-time dynamic linking 
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/*** Call ScrDrawBox through the function pointer. **************************/ 
( *ProcAddr) (ULR,ULC,ULR+11,ULC+39,3,1); 

/*** p r i n t data in window and pause for user's response. ********************/ 
VioWrtCharStr ("DEMONSTRATION WINDOW",20,ULR+3,ULC+9,0); 

VioWrtCharStr ("Press any key to continue ...",29,ULR+6,ULC+4,0); 
VioSetCurPos (ULR+6,ULC+34,0); 

KbdCharln (&Key,0,0); 

/*** Get address of ScrRestore function. ************************************/ 
DosGetProcAddr 

(ModuleHandle, 

"SCRRESTORE", 

&ProcAddr); 

(*ProcAddr) (Selector); 

/*** Restore old cursor position. *******************************************/ 
VioSetCurPos (OldRow,OldCol, 0) ; 

/*** Free the dynamic-link module. ******************************************/ 
Error = DosFreeModule (ModuleHandle); 
if (Error) 

{ 

fprintf (stderr,"Error %d calling DosFreeModule\n",Error); 
exit (1); 

> 

> /* end main */ 


FIGURE 10.7: A program demonstrating run-time dynamic linking (continued) 












CHAPTER 


Writing a 
Monitor 

A monitor is an OS/2 program that filters character-device input or 
output. Once you have installed a monitor for a particular device, all 
characters traveling between the device and the program currently 
performing I/O to this device pass through the monitor, which can 
examine, eliminate, modify, or add characters to the data stream. 
Under OS/2, you can install monitors for the printer, the keyboard, 
and the mouse. Monitors can be used to implement print spoolers, 
keyboard macro programs, cut-and-paste utilities, and many other 
types of background processes. 

This chapter first describes how monitors work, and gives the gen¬ 
eral steps for writing and installing a monitor. The last section then 
presents a cut-and-paste utility, implemented as a keyboard monitor. 
This program allows you to copy a block of data from the screen and 
then insert this data into a program running in any protected mode 
screen group. 
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HOW A A monitor typically runs as a detached background process, globally affect- 

MONITOR ing all applications the user runs in the foreground. (See the sections on 

WORKS background programs in Chapters 1 and 4.) As the foreground applications 

perform input and output to a character device, a monitor that has been 
installed for this device silently inspects the stream of characters moving 
between the application and the device. A monitor can then perform two 
basic types of actions based upon the characters that pass through it. 

First, a monitor can directly manipulate the I/O stream, either remov¬ 
ing, altering, rerouting, or adding characters. For example, a keyboard 
macro utility can replace a single keystroke with an entire sequence of key¬ 
strokes, and a print spooler can intercept all characters written to the printer 
and quickly store these characters in a disk file. Note that in both of these 
cases, the foreground application simply performs normal I/O operations 
and is oblivious to the manipulations that the monitor performs in the back¬ 
ground. A monitor is thus an excellent vehicle for developing an add-on 
utility designed to modify and enhance a variety of applications written by 
other developers. 

Second, a monitor can passively observe the stream of characters until it 
recognizes a special keystroke (a hotkey), whereupon it temporarily runs in 
the foreground and provides services for the user (by means of the video 
pop-up functions described later in this chapter and in Chapter 9). In this 
case, the monitor mechanism is simply a means for the user to temporarily 
suspend the current application and activate a background process. A spell¬ 
ing checker, a thesaurus, a calculator, and a context-sensitive help utility are 
examples of hotkey-activated programs you can implement using the moni¬ 
tor mechanism. 

Note that commonly an application both manipulates the I/O stream 
and uses this stream to detect a hotkey; an example is the cut-and-paste util¬ 
ity presented in the final section of this chapter. 

Figure 11.1 illustrates the flow of characters through a series of monitors 
installed on a given device. Note that several monitors can be installed on 
the same character device. The character source in this diagram is either a 
program or a device, depending upon whether the associated device is an 
input or output device; for example, the source of characters for a keyboard 
monitor is a device, and the source of characters for a printer monitor is a 
program. The device driver passes characters through the chain of monitors 
with the help of a system dispatcher. Since the monitors are installed in 
series, any changes a monitor makes to the I/O stream affect all monitors 
further down the chain (you can request that your monitor be installed at 
one of several specific positions in the chain). Output from the last monitor 
goes back to the device driver, which passes this data to the final target 
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FIGURE 11.1: Flow of characters through a chain of monitors 


(either an output device such as a printer, or a program reading an input 
device such as the keyboard). 

Each monitor must allocate an input and an output buffer (named InBuf 
and OutBuf in Figure 11.1) and must pass the buffer addresses to the sys¬ 
tem. The monitor, however, does not directly manipulate these buffers; 
rather, the system uses them to temporarily store the input that will be read 
by the monitor and the output that has been written by the monitor. The 
monitor must also allocate at least one additional buffer, which it can use to 
receive, manipulate, and write character data. Figure 11.2 provides a close- 
up view showing the flow of characters through a single monitor. The pro¬ 
gramming details are explained in the following sections. 
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DosMonRead 

(Data Transferred by System) 

I 

PROGRAM BUFFER 
(Program Can Change or Discard) 


DosMonWrite 

(Data Transferred by System) 

t 

OUTPUT BUFFER 
MANAGED BY THE SYSTEM 


FIGURE 11.2: Flow of characters through a single monitor 

Note that each character sent through the monitor chain is represented 
not by a single byte, but rather by a complete packet of information Gust as 
functions such as KbdCharln supply not only a single character, but also an 
entire structure of related information). The format of these packets is 
device-specific; however, all packets begin with a one-word flag containing 
information appropriate for the particular device. (The structure of a key¬ 
board monitor packet is described in the final section of this chapter.) A 
monitor typically reads (through DosMonRead) and writes (through Dos¬ 
MonWrite) a single packet at a time. However, a monitor could also transfer 
multiple packets with a single operation, buffering these packets within a 
data segment owned by the monitor process. (If the monitor buffers packets 
internally, it must be prepared to discard this data if it receives a flush 
request; for keyboard monitors, bit 10 of the monitor flag word is set 
to request a flush operation.) 

Note also that the device driver does not necessarily pass all character 
data through the monitor chain. For example, the keyboard device driver 
does not send the system hotkeys (Alt-Escape and Control-Escape) through 
the monitors; therefore, you cannot intercept these keys. Also, you cannot 
install a monitor unless the driver for the associated device specifically sup¬ 
ports monitors. Theoretically, any character-device driver could support 
monitors; you can install monitors for the standard OS/2 device drivers for 
the printer, the keyboard, and the mouse. You can also determine whether a 
specific device driver supports monitors by calling an I/O control function 
(category OBh, function 60h; see Appendix C). Finally, note that a printer 
monitor will receive output from all screen groups in the system (including 
the real mode screen group), since all processes share a single physical 
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printer. However, since keyboard and mouse input comes from virtual 
devices that are distinct for each screen group, a monitor for either of 
these devices receives input only from the single screen group for which it 
was specifically installed. 


The well-documented and reliable methods provided by OS/2 for writing 
and installing device monitors should delight the programmer who has tried 
to perform similar tasks under MS-DOS. The following are the general 
steps for installing a monitor for a character device; the specific procedures 
for installing a keyboard monitor are presented in the next section. 

1. Allocate the input and output buffers that the system uses to man¬ 
age the monitor data. 

2. Call DosMonOpen to open the monitor for the specific device. 

This function returns a handle that must be passed to the OS/2 
monitor functions that are subsequently called. 

3. Call DosMonReg to register the monitor buffers allocated in 
step 1. Once you make this function call, the monitor is linked to 
the character stream and must immediately begin transferring data 
from the input to the output buffer. (Each monitor in the chain 
must actively transfer characters; otherwise, the flow of characters 
for the associated device will stop.) 

4. The monitor must now enter a loop that repeatedly calls Dos- 
MonRead to read characters from the input buffer and calls 
DosMonWrite to write characters to the output buffer. Note that 
since the monitor is free to discard or insert characters, the num¬ 
ber of characters read does not necessarily equal the number writ¬ 
ten. Remember, however, that only characters explicitly written by 
calling DosMonWrite will be received by subsequent monitors on 
the chain. 

5. When the monitor is no longer required, you can call DosMon- 
Close to flush all characters associated with the monitor and 
remove the monitor from the chain. 

Note that the speed of character transfer between a program and a device 
is bound by the slowest monitor installed on the chain. Therefore, the main 
loop that reads, processes, and writes these characters should be as efficient 
as possible. In addition to writing efficient code, you should call DosSet- 
Prty to place the thread that executes this loop in the time-critical priority 
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class. (Monitors almost always run as background processes, which are nor¬ 
mally assigned a lower priority level than the foreground processes. A 
thread assigned to the time-critical priority class, however, executes at a 
higher priority than normal foreground processes. See the description of 
priority classes and levels in Chapter 6.) If the monitor needs to perform 
additional tasks not part of the main character-processing loop, these tasks 
should be relegated to a separate thread (or several threads), which run at 
normal priority. 

A monitor program can be loaded and executed as a detached process in 
the background through one of the following three commands: 

♦ The RUN command in the configuration file, which loads and 
starts a single instance of the monitor at system initialization. This 
technique is most useful for monitors such as print spoolers that 
need to be loaded only once and can service all screen groups that 
are subsequently started. 

♦ The DETACH command, which loads the monitor from the com¬ 
mand interpreter belonging to a particular screen group. This is 
useful for installing a monitor such as a keyboard utility that needs 
to be loaded separately in each screen group. For convenience, you 
can place this command in the OS2INIT.CMD file so that the 
monitor will automatically be loaded when each new screen group 
is started. 

♦ You can run a monitor in the background from a parent program 
by calling DosExecPgm, assigning a value of 4 to the execution 
flag (parameter 3). This method is also useful for keyboard and 
mouse monitors, and has the advantage that the parent process 
can be loaded directly from the command line (without using 
DETACH), and the parent can perform initialization tasks and 
check that the monitor has not already been loaded. For an 
example, see the cut-and-paste utility described in the next section. 


This final section presents the complete source code for a cut-and-paste util¬ 
ity implemented as a keyboard monitor that runs as a detached process. The 
listings are contained in Figures 11.3 and 11.4. This is the last example pro¬ 
gram in the book and serves to illustrate not only the monitor mechanism, 
but also the following topics discussed in prior chapters: 

♦ Using shared memory for exchanging data among separate 
processes 
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§ Using system semaphores for synchronizing the activities of multi¬ 
ple processes 

❖ Using many of the video and keyboard subsystem functions 

♦ Using the video pop-up mechanism 


/* 

Figure 11.3 

This program loads the keyboard monitor cut-and-paste utility, FIG11_4.EXE. 
You can prepare the program using the following commands 


cl /G2 /Zp /Lp figll_3.c 

*/ 

♦define INCL_DOS 
♦define INCL_DOSERRORS 
♦include <os2.h> 

♦include <stdio.h> 

♦include <process.h> 


struct ShareMem /* Structure for accessing the shared memory segment. */ 


•[ 

int ScreenGroups [12]; 
int DataLength; 
int RowLength; 
char ScreenData [25 * 80]; 


/* Table listing installed monitors. */ 
/* Length of paste data in buffer. */ 
/* Row length for paste data. */ 
/* Buffer to store paste data (assumes a */ 
/* 25-line text model */ 


struct /* Structure to contain arguments passed to monitor process. */ 

< 

char ChildName [12]; 
char Argl [3]; 

} 

Arguments = 

i 

"FIG11_4.EXE" 

> ? 


void main () 

{ 

int i,j; 
unsigned Error; 
unsigned short Selector; 
int SegExists; 

struct ShareMem far *PtrShareMem; 
void far *SemHandle; 
unsigned short GlobalSeg; 
unsigned short LocalSeg; 

LINFOSEG far *PtrLocalSeg; 
char ObjectName [13]; 

RESULTCODES ExecResult; 


/* Stores API function error codes. */ 
/* Selector for shared segment. */ 
/* Shared segment exists flag. */ 
/* Accesses shared memory segment. */ 
/* System semaphore handle. */ 
/* Global information segment. */ 
/* Local information segment. */ 
/* Accesses local info, segment. */ 
/* Used by DosExecPgm. */ 
/* Used by DosExecPgm. */ 
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/*** Allocate the shared memory segment. *************************************/ 
Error = DosAllocShrSeg 

(sizeof (struct ShareMem), /* Number of bytes in segment. */ 

"\\SHAREMEM\\@PASTE@.DAT", /* Name of shared segment. */ 

&Selector); /* Variable to receive selector. */ 

if (Error == 0) 

SegExists = 0; 

else if (Error == ERROR_ALREADY_EXISTS) /* Segment already exists; */ 

{ /* monitor(s) already loaded. */ 

SegExists =1; 

Error = DosGetShrSeg /* Get a handle to segment. */ 

("\\SHAREMEM\\@PASTE@.DAT", 

&Selector); 
if (Error) 

{ 

fprintf (stderr,"Error %d calling DosGetShrSeg\n",Error); 

DosExit (1,1); 

} 

> 

else /* Unexpected error code from DosAllocShrSeg. */ 

fprintf (stderr,"Error %d calling DosAllocShrSeg\n",Error); 

DosExit (1,1); 

/* Create pointer to access shared memory segment. */ 

PtrShareMem = (struct ShareMem far *) MAKEP (Selector,0); 

/*** Get current screen group. ***********************************************/ 
Error = DosGetlnfoSeg 
(SGlobalSeg, 

&LocalSeg); 
if (Error) 

{ 

fprintf (stderr,"Error %d calling DosGetInfoSeg\n",Error); 

DosExit (1,1); 

/* Create a pointer to access local information segment, current screen */ 
/* group field. */ 

PtrLocalSeg = (LINFOSEG far *)MAKEP (LocalSeg,0); 


/*** Initialize shared memory segment. ***************************************/ 
if (SegExists) /* Monitor(s) are already installed. */ 

j = -1; /* j stores a free table entry. */ 

for (i = 0;i <= ll;++i) /* Search table for current screen group. */ 

if (PtrShareMem->ScreenGroups [i] == PtrLocalSeg->sgCurrent) 

{ 

fprintf (stderr,"Monitor already installed in this " 

"screen group.\n"); 

DosExit (1,1); 

} 

if (PtrShareMem->ScreenGroups [i] == -1) 
j = i; 

> /* end for */ 

if (j == -1) /* No free entries found; this should not happen */ 

/* in OS/2 version 1.0. */ 

{ 

fprintf (stderr,"Monitor installed in too many screen " 

"groups.\n"); 

DosExit (1,1); 

> 


FIGURE 11.3: A program that loads the cut-and-paste monitor of Figure 11.4 (continued) 





Writing a Monitor 


/ 


e l se /* Add current screen group to table. */ 

PtrShareMem->ScreenGroups [j] = PtrLocalSeg-->sgCurrent; 

else * /* Segment does NOT exist; no monitors currently installed. */ 

j * Therefore initialize the new shared memory segment. */ 

PtrShareMem->ScreenGroups [0] = PtrLocalSeg->sgCurrent; 
for (i = 1;i <= ll?++i) 

PtrShareMem->ScreenGroups [i] = -1; 

PtrShareMem->DataLength = 0; 

PtrShareMem->RowLength = 0; 

> 

/*** Allocate and set a system semaphore. ***********************************/ 
Error = DosCreateSem , 

m /* indicates nonexclusive ownership. */ 

StSemHandle, /* Variable to receive handle. */ 

"\\SEM\\@PASTE@.LCK"); /* Name of semaphore. / 

if (Error) 

fprintf (stderr,"Error %d calling DosCreateSem\n",Error); 

DosExit (1,1); 

Error^ DosSemSet (SemHandle); 
if (Error) 

fprintf (stderr,"Error %d calling DosSemSet\n",Error); 

DosExit (1,1); 

} 

/*** Execute the monitor process. *******************************************/ 
sprintf (Arguments.Argl,"%d",PtrLocalSeg->sgCurrent); 

Error = DosExecPgm ^ ^ n , . / 

/* Receives name of file that failed. */ 
/* Size of buffer to receive file name.*/ 
/* Execute detached in background. */ 

/* Argument string passed to child. */ 


(ObjectName , 
sizeof (ObjectName) J 

4 r 

(char *)&Arguments, 
0 , 

SExecResult, 
"FIG11_4.EXE"); 


/* Pass parent's environment. 
/* Receives process ID. 

/* Name of program to execute. 


■k -k -k ic I 
*/ 


if (Error) 

fprintf (stderr,"Error %d calling DosExecPgm\n ", Error); 

DosExit (1,1); 

> 

/*** Before terminating, wait for monitor process to grab shared memory. 

Error = DosSemWait 
(SemHandle, 

5000L) ; /* Wait up to 5 seconds, 

if (Error) 

fprintf (stderr,"Error %d calling DosSemWait\n", Error); 

DosExit (1,1); 

} 

/*** Free access to shared memory and semaphore and exit. *******************/ 
DosFreeSeg (Selector); 

DosCloseSem (SemHandle); 

DosExit (1,0); 

} /* end main */ 


FIGURE 11.3: A program that loads the cut-and-paste monitor of Figure 1L4 (continued) 
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Figure 11.4 


/* 

Figure 11.4 


This program provides a cut-and-paste utility. It is executed as a 
detached process by FIG11_3.EXE. You can prepare the program using the 
following commands 


cl /G2 /Zp /Lp figll_4.c 

*/ 

#define INCL_BASE 
#include <os2.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <string.h> 


#define MONBUFSIZE 128 

#define ULR 6 
#define ULC 20 


/* Size of monitor input and output buffers. 

/* Position of upper corner of pop-up windows. 
/* Upper left row. 

/* Upper left column. 


/* Table listing installed monitors. 

/* Length of paste data in buffer. 

/* Row length for paste data. 

/* Buffer to store paste data (assumes a 
/* 25-line text mode!). 


struct ShareMem 
{ 

int ScreenGroups [12]; 
int DataLength; 
int RowLength; 
char ScreenData [25 * 80]; 


struct ShareMem far *PtrShareMem; 

struct KeyPacket 

{ 

unsigned MonFlags; 

KBDKEYINFO Data; 
unsigned DevFlags; 

}; 

struct KeyPacket OutKey = 

{ 

0 , 

{ 0 , 0 , 0 , 0 , 0 , 01 , 

0 

}? 

struct KeyPacket CarriageReturn = 

{ 

0 , 

{13,28,0,0,0,0}, 

0 

}? 

unsigned Error; 
unsigned int ScreenGroup; 
unsigned short Selector; 
unsigned short MonHandle; 
unsigned char InBuf [MONBUFSIZE]; 
unsigned char OutBuf [MONBUFSIZE]; 


/* C pointer for shared memory segment. 

/* Keyboard data packet structure. 

/* Keyboard monitor flags. 

/* Keyboard data. 

/* Keyboard device flags. 


/* Packet for writing paste characters. 


/* Packet for adding carriage returns 
/* to pasted data. 


/* Stores API function error codes. 
/* Screen group of parent process. 
/* Selector for shared segment. 

/* Handle to monitor. 

/* Monitor input buffer. 

/* Monitor output buffer. 


*/ 

*/ 


FIGURE 11.4: A cut-and-paste utility implemented as a keyboard monitor 
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* / 

/* Local function declarations. . 1 • +. 7 

void ErrorQuit (char *FunctionName, unsigned ErrorNum, char *File, mt Line), 

void QueryQuit (void)? 
void Cut (void); 
void Paste (void )) 

void MarkBlock (int StartRow,int Started,int EndRow,int EndCol); 
void CopyBlock (int StartRow,int StartCol,int EndRow,mt EndCol); 

void main (int argc,char *argv[]) 

void far *SemHandle; /* Handle to system semaphore. */ 


void far *SemHandle; /* Handle to system semaphore. */ 

c- 1 -rnrt KevPacket Key /* Structure to hold keyboard packet.*/ 

i.nt KeySh; ^ !' Holds length of 'Key' structure. */ 

/*** Grab the shared memory segment. ******************* / 

Error = DosGetShrSeg „ , . */ 

("\\ SHAREMEM\\@PASTE@.DAT", /* Global name of shared segment. / 

^Selector); /* Variable to receive selector. */ 

if (Error) 

ErrorQuit ("DosGetShrSeg",Error,_FILE_,_LINE—)? 

PtrShareMem = (struct ShareMem far *) MAKEP (Selector,0); 

/*** Obtain, clear, and close system semaphore PASTES? .LCK" *****************/ 

Error = DosOpenSem . , , ,, */ 

(&SemHandle, /* Variable to receive semaphore handle. / 

"\\SEM\\@PASTE®.LCK"); /* Global name of semaphore. / 

if (Error) 

ErrorQuit ("DosOpenSem",Error,_FILE_,_LINE_); 

Error = DosSemClear (SemHandle); 
if (Error) 

ErrorQuit ("DosSemClear",Error, FILE , LINE )? 

Error = DosCloseSem (SemHandle); 
if (Error) 

ErrorQuit ("DosCloseSem",Error, FILE , LINE ); 

/*** Open the monitor. *******************************************************/ 

= BDs“° n0Pen /* Name of keyboard device. */ 

SMonHandle); /* Receives handle to monitor. */ 

.if (Error) , 

ErrorQuit ( "DosMonOpen",Error, FILE , LINE ) ,° 

/*** increase the process priority. ******************************************/ 
Error = DosSetPrty , 

(0, /* Affects all threads in current process. / 

3 f /* Time-critical priority class. */ 

0, /* Do not change base priority level. J 

0); /* Indicates the current process. */ 

if (Error) 

ErrorQuit ( "DosSetPrty",Error, FILE , LINE ) ,° 

/*** Register the monitor buffers. *******************************************/ 
InBuf [0] = OutBuf [0] = MONBUFSIZE; /* Place buffer size m buffer. */ 

ScreenGroup = atoi (argv [1]); /* Get screen, group of parent. */ 

Error = DosMonReg , 

(MonHandle, /* Handle to monitor. */ 

XnBuf, /* Address of input buffer. */ 

OutBuf, /* Address of output buffer. */ 
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0' /* Any pos 

ScreenGroup); /* Install 

if (Error) 

ErrorQuit ("DosMonReg",Error, FILE 


/* Any position is OK. 

/* Install in parent's screen group. 


/*** Monitor read/write loop. ****************************************. 

(?;) . 

{ 

KeyLength = sizeof (Key); 

Error = DosMonRead 

(InBuf, /* Address of monitor input buffer. 

/* Wait until packet is ready. 

(char *)&Key, /* Receives the data. 

SKeyLength); /* Read a single keyboard packet, 

if (Error) 

ErrorQuit ("DosMonRead",Error, FILE , LINE \• 

if (Vox? Haf a - a c 77 , , . —— ;-. . -- >' 


if (Key.Data.chScan == 45 && 'J* Alt- 

Key . Data . fsState & 0x0008) 

if (Key.DevFlags & 0x0040) /* Disc 

continue; 

QueryQuit (); 
continue; 

} 

if (Key.Data.chScan == 46 && /* Alt- 

Key . Data . fsState & 0x0008) 

if (Key.DevFlags & 0x0040) /* Disc 

continue; 

Cut (); 
continue; 

> 

if (Key.Data.chScan == 25 && /* Alt- 

Key . Data . fsState & 0x0008) 

if (Key.DevFlags & 0x0040) /* Disc 

continue; 

Paste (); 
continue; 

> 

Error - DosMonWrite /* Pass data pack 

(OutBuf, /* Address of out 

(char *)&Key, /* Contains data 

KeyLength); /* Write a single 

if (Error) 

ErrorQuit ("DosMonWrite", Error,_FILE 

} /* end forever loop */ 


7* Alt—X hotkey! 

/* Discard released key. 


/* Alt-C hotkey! 

/* Discard released key. 


/* Alt-P hotkey! 

/* Discard released key. 


/* Pass data packet onto monitor chain. 
/* Address of output buffer. 

/* Contains data to write. 

/* Write a single data packet. 


_LINE_) ; 


} /* end main */ 

void ErrorQuit (char *FunctionName, unsigned ErrorNum, char *File, int Line 

This function prints a error message in a pop-up window and terminates 
the monitor process. 

*/ 

{ 

unsigned int WaitFlag; /* Passed to VioPopUp. 

int r - ULR; /* Position of upper left corner of pop-up window. 
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int c = ULC? 
unsigned char a = 0x07; 

char Buffer [16]? /* For formatting data with 'sprintf'. 

KBDKEYINFO Key? /* Holds a keystroke received from 'KbdCharln' 


WaitFlag = 0x0002? 
Error = VioPopUp 
(&WaitFlag, 
0 )? 

if (Error) 

Quit ()? 


/* Open a pop-up screen group. 

/* No wait / transparent pop-up. 


/* Must be 0. 


VioWrtCharStrAtt ("- / 

VioWrtCharStrAtt( " Cut & Paste Monitor Error "/ 

VioWrtCharStrAtt(" " > 

VioWrtCharStrAtt(" function called? "/ 

VioWrtCharStrAtt(" error numbers ", 

VioWrtCharStrAtt(" source files " / 

VioWrtCharStrAtt(" line numbers \ 

VioWrtCharStrAtt( " "> 

VioWrtCharStrAtt(" Press any key to continue ... ", 

VioWrtCharStrAtt(" % 

VioWrtCharStrAtt(" " / 

VioWrtCharStrAtt ( "- "' 

VioWrtCharStrAtt(FunctionName,strlen (FunctionName), ULR+3, U 
sprintf (Buffer,"%d",ErrorNum)? 

VioWrtCharStrAtt(Buffer,strlen (Buffer),ULR+4,ULC+20,&a,0)? 
VioWrtCharStrAtt(File,strlen (File),ULR+5,ULC+20,&a,0)? 
sprintf (Buffer,"%d”,Line)? 

VioWrtCharStrAtt(Buffer,strlen (Buffer),ULR+6,ULC+20,&a,0)? 


",40,r++ 
" ,40,r++ 
",40,r++ 
" ,40,r++ 
" ,40,r++ 
",40,r++ 
",40,r++ 
",40,r++ 
",4 0,r++ 
",40,r++ 
",40,r++ 
",40,r++ 
,ULC+20, 


,c,&a,C 
,c, &a, C 
,c,&a,C 
,c, &a, C 
,c, &a, C 
,c, &a, C 
,c, &a, C 
,c, &a, ( 
,c, &a, ( 
,c, &a, ( 
,c,&a, ( 
,c,&a,( 
&a,0) ? 


KbdCharln (&Key,0,0)? 

VioEndPopUp (0)? 

Quit (); 

} /* end ErrorQuit */ 


/* Pause for user to press a key. 

/* Restore original screen group. 
/* Terminate process. 


void QueryQuit () 

unsigned int WaitFlag? /* Passed to VioPopUp. 

int r = ULR? /* Position of upper left corner of pop-up window. 

int c = ULC? 

unsigned char a = 0x07? 

KBDKEYINFO Key? /* Holds a keystroke received from 'KbdCharln'. 

VIOCURSORINFO Cursor? /* Hold cursor type for 'VioSetCurType'. 

/* Open a pop-up screen group. 

WaitFlag = 0x0002? /* No wait / transparent pop-up. 

Error = VioPopUp 
(&WaitFlag, 

0)? /* Must be 0. 

if (Error) 

ErrorQuit ("VioPopUp",Error,_FILE_,_LINE_)? 
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VioWrtCharStrAtt(" 
VioWrtCharStrAtt(" 
VioWrtCharStrAtt(" 
VioWrtCharStrAtt(" 
VioWrtCharStrAtt(" 
VioWrtCharStrAtt(" 
VioWrtCharStrAtt(" 
VioWrtCharStrAtt(" 
VioWrtCharStrAtt(" 
VioWrtCharStrAtt(" 
VioWrtCharStrAtt(" 
VioWrtCharStrAtt(" 


Cut & Paste Utility 


Do you want to remove the monitor 
from this screen group? 

(y/n)! 


",40,r++,c,&a, 0) 
" / 40,r++, c,&a,0) 
",40,r++,c,&a, 0) 
",40,r++,c,&a, 0) 
",40,r++,c,&a,0) 
"/40,r++,c,&a, 0) 
",40,r++, c,&a,0) 
", 40,r++,c,&a, 0) 
" ,40,r++,c,&a,0) 
”,40,r++,c,&a,0) 
", 40,r++, c,&a,0) 
" ,40 r r++ r c,&a,0) 


Cursor.yStart = 0; 

Cursor.cEnd = 13; 

Cursor.cx = 0; 

Cursor.attr = 0; 

VioSetCurType (&Cursor,0); 
VioSetCurPos (ULR+7,ULC+20,0); 
KbdCharln (&Key,0,0); 


/* Display a full block 


if^Error j° EndP ° PUP ^ Restore original screen group 

ErrorQuit ("VioEndPopUp", Error , _FILE , LINE ); 


cursor. 


*/ 


*/ 


/* Quit if user types 1 Y’. 

if (Key.chChar == ’y’ || Key.chChar == ’Y') 

Quit (); 

else 

return; 


> /* end QueryQuit */ 


void 

/* 


*/ 


!*** 


Cut () 


This function marks a section of 
the shared memory segment. 


the screen and copies the data to 


{ 

unsigned int WaitFlag; 
VIOCURSORINFO Cursor; 
int Marking = 0; 
unsigned StartRow,StartCol; 
unsigned EndRow,EndCol; 
KBDKEYINFO Key; 


/* Passed to VioPopUp. 

/* Holds cursor type for ’VioSetCurType’. 
/* Indicates block is being marked. 

/* Dimensions of block on screen. 

/* Holds a keystroke from ’KbdCharln’. 


Display popup. ******************************************************** 
WaitFlag = 0x0002; /* No wait / transparent pop-up. 

Error = VioPopUp 
(&WaitFlag, 

0); /* Must be 0. 

if (Error) 

ErrorQuit ("VioPopUp", Error,_FILE_ , _LINE ); 


* * j 
*/ 


/*** Full block cursor, ^t*******************************************^.^*^*^^ , 
Cursor.yStart =0; ' 

Cursor.cEnd = 13; 

Cursor.cx = 0; 

Cursor.attr = 0; 

VioSetCurType (&Cursor,0); 
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/* B. 

/* Set on marking flag. 

/* Initialize start and 
/* stop block dimensions. 
/* Hide cursor. 


*/ 

*/ 

*/ 

*/ 

*/ 


/*** Get initial cursor position. ********************************************/ 
VioGetCurPos (&StartRow,&StartCol,0); 

/*** Keyboard read loop. *****************************************************/ 
for (?;) 

{ 

KbdCharln (&Key,0,0); 
switch (Key.chScan) 

{ 

case 48: 

Marking = 1; 

EndRow = StartRow; 

EndCol = Started; 

Cursor.yStart = 0; 

Cursor.cEnd = 0; 

Cursor.cx = 0; 

Cursor.attr = Oxffff; 

VioSetCurType ( ^Cursor, 0 ) ; 

/* Mark first block. 

MarkBlock (StartRow,StartCol,EndRow,EndCol); 
break; 

case 72: /* Up arrow, 

if (Marking && EndRow > 0) 

MarkBlock (StartRow,StartCol,--EndRow,EndCol); 
if ({Marking && StartRow > 0) 

VioSetCurPos (—StartRow,StartCol,0); 
break; 

case 80: /* Down arrow, 

if (Marking && EndRow < 24) 

MarkBlock (StartRow,StartCol,++EndRow,EndCol); 
if (1Marking && StartRow < 24) 

VioSetCurPos (++StartRow,StartCol,0); 
break; 

case 75: /* Left arrow, 

if (Marking && EndCol > 0) 

MarkBlock (StartRow,StartCol,EndRow,--EndCol); 
if ({Marking && StartCol > 0) 

VioSetCurPos (StartRow,--Started,0); 
break; 

case 77: /* Right arrow, 

if (Marking && EndCol < 79) 

MarkBlock (StartRow,StartCol,EndRow,++EndCol); 
if ({Marking && StartCol < 79) 

VioSetCurPos (StartRow,++StartCol,0); 
break; 

case 1: /* Escape, 

if (Marking) 

CopyBlock (StartRow,StartCol,EndRow,EndCol); 

Error = VioEndPopUp (0); 
if (Error) 

ErrorQuit ("VioEndPopUp", Error,_FILE_,_LINE 

return; 
break; 

} /* end switch */ 

> /* end forever loop */ 

} /* end Cut */ 


_)? 
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void Paste () 

/* 

This function inserts the block of screen data saved in the shared memory 
segment into the keyboard data stream. 

*/ 

{ 

register int i; 


for (i = 0;i < PtrShareMem->DataLength;) 

OutKey.Data.chChar = PtrShareMem->ScreenData [i]; 

Error = DosMonWrite 
(OutBuf, 

(char *)&OutKey, 
sizeof (OutKey)); 
if (Error) 

ErrorQuit ("DosMonWrite", Error,_FILE_,_LINE ); 

/* Add a carriage return at the end of each row of screen data, 
if (++i % PtrShareMem->RowLength == 0) 

Error = DosMonWrite 
(OutBuf, 

(char *)&CarriageReturn, 
sizeof (CarriageReturn)); 
if (Error) 

ErrorQuit ("DosMonWrite",Error,_FILE_,_LINE ); 

} /* end for */ 

> /* end Paste */ 


void Quit () 

/* 

function removes the monitor's screen group from the shared memory 
^ table, releases resources, and terminates the process. 

{ 

int i; 

for (i = 0;i <= 11; ++i) 

if (PtrShareMem->ScreenGroups [i] == ScreenGroup) 

PtrShareMem->ScreenGroups [i] = - 1 ; 
break; 

} 

DosMonClose (MonHandle); 

DosFreeSeg (Selector); 

DosExit (1,0); 

} /* end Quit */ 


void MarkBlock (int StartRow,int StartCol,int EndRow,int EndCol) 


/* 

*/ 


This function highlights the current block on the screen. 


{ 

unsigned int SR,SC,ER,EC; 
unsigned int Row,Col; 
unsigned int NumCols; 


/* Starting/ending row/column. 
/* Loop counter. 

/* Number of columns to mark. 
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/* Make entire screen intense white on black. / 

VioWrtNAttr ("\x0f",25 *80,0,0,0); 

if (StartRow < EndRow) /* Make sure that starting row/column are less */ 
{ /* than ending row/column. */ 

SR = StartRow; 

ER = EndRow; 

> 

else 

{ 

SR = EndRow; 

ER = StartRow; 

if (Started < EndCol) 

{ 

SC = StartCol; 

EC = EndCol; 

> 

else 

{ 

SC = EndCol; 

EC = StartCol; 

NumCols = EC - SC + 1; 

for (Row = SR;Row <= ER;++Row) 

VioWrtNAttr ("\x7 0",NumCols,Row,SC,0); 

} /* end MarkBlock */ 


void 

/* 


*/ 


CopyBlock (int StartRow,int StartCol,int EndRow,int EndCol) 

This function copies the current screen block to the shared memory 
segment. 


{ 

int i; 

unsigned int SR,SC,ER,EC; /* 

unsigned int Row,Col; /* 

unsigned int NumCols; /* 

if (StartRow < EndRow) /* Make 

{ /* than 

SR = StartRow; 

ER = EndRow; 

> 

else 

{ 

SR = EndRow; 

ER = StartRow; 

if (StartCol < EndCol) 

{ 

SC = StartCol; 

EC = EndCol; 

} 

else 

{ 

SC = EndCol; 

EC = StartCol; 

} 


Starting/ending row/column. 

Loop counter. 

Number of columns to mark. 

sure that starting row/column are less 
ending row/column. 
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for (Row = SR;Row <= ER;++Row) 

NumCols = EC - SC + 1; 

Error = VioReadCharStr 

((char far *)&PtrShareMem->ScreenData [i], /* Buffer to 


SNumCols, /* Number of characters to copyt 

^ ow ' /* Starting row on screen. 

/* Starting column on screen. 

0) ; /* Must be 0. 

if (Error) 

ErrorQuit ("VioReadCharStr",Error, FILE 
i += NumCols; 


7* receive screen data. */ 


_LINE_) ; 


} /* end for */ 

PtrShareMem->DataLength = i; 
PtrShareMem->RowLength = NumCols; 

} /* end CopyBlock */ 


/* Update information in header of */ 
/* shared memory segment. *j 


FIGURE 11.4: A cut-and-paste utility implemented as a keyboard monitor (continued) 


How to Use the Cut-and-Paste Utility 

The cut-and-paste utility allows you to copy any rectangular section of the 
screen (or the entire screen) and then insert this data into a program running 
in any screen group; the program will receive the data as if it were entered 
from the keyboard. This utility thus provides a simple form of interprocess 
communication that is under the direct control of the user. Before describ¬ 
ing the implementation details, this section outlines the procedures for 
loading and using the program. 

The first step is to load the monitor by running the program listed in Fig¬ 
ure 11.3, as follows: 

figl 1_3 

You must run this program in every screen group in which you want to use 
the cut-and-paste utility (for convenience, you can place the command in 
the OS2INIT.CMD file so that it will automatically be executed each time 
you start a new screen group). FIG11_3 performs some housekeeping 
duties and then loads the actual monitor program, FIG11_4.EXE, as a 
detached process. FIG11_4 must therefore be in the current directory or in 
a directory given in your PATH command. If the monitor has already been 
loaded in the current screen group, the program will print an error message 
and will not load a second copy. 

After FIG 11_3.EXE loads the monitor, it terminates and returns control 
immediately to the OS/2 command prompt. The monitor, however, 
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remains running as a detached process, and can be accessed through the fol¬ 
lowing hotkeys: 

HOTKEY ACTION 

Alt-C Cut. This key allows you to copy a rectangular block of screen 
data into an internal buffer. When you press Alt-C, the cursor 
assumes a full block shape and can be moved on the screen using 
the four arrow keys. When you have placed the cursor on one of 
the corners of the block you would like to copy, type B to mark 
the begi nnin g of the block. All characters on the screen 
immediately become white on a black background, and the cursor 
position is highlighted. You can now use the four arrow keys to 
extend the highlighted block in any direction. When you have 
highlighted the desired area, press Escape to copy the block and 
restore the original screen. Each time you use this command, the 
new data replaces the last data copied into the buffer. 

Alt-P Paste. Pressing this key inserts the last block of data copied with 
Alt-C into the input stream of the program currently reading the 
keyboard. The characters are accepted just as if they were typed 
from the keyboard. Note that the program receiving the 
characters need not be in the same screen group as the screen 
from which the characters were copied. 

Alt-X Exit. When you press this key, the monitor will ask whether you 
want to remove the cut-and-paste utility from the current screen 
group. Type Y to remove it, or press any other key to keep it in 
memory. 

Note that the manner in which certain characters are interpreted depends 
upon the receiving program. A good example is the character having an 
ASCII value of 13. This character is originally displayed on the screen as a 
musical note; the receiving program, however, may interpret it as a carriage 
return or some other control command (the keyboard generates a character 
value of 13 in response to the Enter or Control-M keystroke). 

How the Cut-and-Paste Utility Works 

The cut-and-paste utility is implemented as two separate programs. The 
program in Figure 11.3 is executed from the command line as a normal 
foreground process; this program first performs some initialization tasks 
and then executes the actual monitor program as a detached process. The 
monitor program is listed in Figure 11.4. 
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The Foreground Program 

The foreground program listed in Figure 11.3 performs the following 
sequence of steps: 

1. It calls DosAllocShrSeg to allocate a named shared memory seg¬ 
ment that can be used by one or more monitor processes to store 
the data copied from the screen. A successful return code indi¬ 
cates that no other cut-and-paste monitors are currently installed, 
and that a new shared memory segment has been allocated. If, 
however, DosAllocShrSeg returns an error code signifying that the 
segment already exists, then one or more monitors are currently 
installed and the program must call DosGetShrSeg to obtain a 
handle to the segment. 

2. The program calls DosGetlnfoSeg to obtain the identifier of the 
current screen group. 

3. If no other monitors are presently installed, the program initi aliz es 
the new shared memory segment. The beginning of this segment is 
used to contain a table of 12 screen group identifiers (12 is the 
maximum number of screen groups). Each time a monitor is 
installed, the current screen group ID is placed in a free entry in 
this table (free entries are indicated by - 1); if the monitor is sub¬ 
sequently released, the entry is marked free. 

4. If one or more monitors are currently installed, the program 
searches the table at the beginning of the shared memory segment 
to make sure that a monitor is not already installed in the current 
screen group. If a monitor is installed, the program exits with an 
error message; otherwise, it places the current screen group ID into 
a free entry in the table. 

5. Next, the program creates and sets a system semaphore (using 
DosCreateSem and DosSemSet). This semaphore will subsequently 
be cleared by the monitor process to signal that it has obtained a 
handle to the shared memory segment and that the parent process 
can safely terminate. If a semaphore were not used, the parent 
process would most likely terminate (and therefore release the 
shared memory segment) before the monitor process was able to 
obtain a handle to this segment. 

6. The program now calls DosExecPgm to execute the monitor as a 
detached process, passing it the identifier of the current screen 
group as a parameter. 
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7. Before terminating, the program calls DosSemWait to wait for the 
monitor process to clear the system semaphore. Note that it speci¬ 
fies a maximum wait of 5 seconds; otherwise, if the monitor 
encounters an error and is unable to clear the semaphore, the par¬ 
ent program would never return control to OS/2. 

The Monitor Program 

Once the monitor program of Figure 11.4 has been loaded into the back¬ 
ground, it performs the following operations: 

1. It calls DosGetShrSeg to obtain a handle to the shared memory 
segment that is used by all currently installed monitors to store 
screen data and other information. 

2. The program calls DosOpenSem to obtain a handle to the system 
semaphore set by the parent process, and then calls DosSemClear 
to clear this semaphore and DosCloseSem to relinquish its access 
to the semaphore. The parent process is now free to terminate. 

3. The program now calls DosMonOpen to open a keyboard monitor. 

4. Before the program links itself to the chain of monitors that pro¬ 
cess the stream of keyboard data, it calls DosSetPrty to place itself 
in the time-critical priority class. 

5. The program now calls DosMonReg to register its input and out¬ 
put buffers, and thereby place itself in the chain of monitors 
within the screen group requested by the parent process. Note that 
the input and output buffers (InBuf and OutBuf) are both 
assigned a length of 128 bytes, which is the size recommended by 
the OS/2 Programmer’s Reference (64 bytes is the minimum). 

6. The program now enters the main processing loop, which calls 
DosMonRead to read a keyboard character packet, examines this 
packet for one of its three hotkeys (Alt-X, Alt-C, and Alt-P), and 
then calls DosMonWrite to write the packet back to the character 
stream if none of the hotkeys is detected. 

7. If the program detects the Alt-X (exit) hotkey, it calls the function 
Query Quit, which displays a pop-up window that asks the user 
whether to remove the monitor from the current screen group. If 
the user chooses to remove the monitor, the program calls Dos- 
MonClose to release the monitor, it calls DosFreeSeg to relinquish 



the shared memory segment, and finally it calls DosExit to termi¬ 
nate the process. To display the pop-up window, the function first 
calls VioPopUp, which grants the monitor process access to the 
screen and keyboard; it then displays the window data using the 
VioWrtCharStr function, and finally restores the foreground 
screen by calling VioEndPopUp. 

8. If the program detects the Alt-C (cut) hotkey, it calls the function 
Cut, which allows the user to mark and copy a block of screen 
data into the shared memory segment. Cut first calls VioPopUp, 
requesting the transparent option, which means that when the 
system switches to the pop-up screen it leaves the original data on 
the screen. The Cut function consists mainly of a keyboard¬ 
reading loop. (Note that when a process calls VioPopUp, it tempo¬ 
rarily runs in the foreground in a special screen group reserved for 
pop-up routines. The program can thus read the keyboard like a 
normal foreground process. Also, the keystrokes it reads are not 
processed by the monitor loop in the main function, since the 
screen group for which this monitor is installed is now temporarily 
in the background.) The keyboard loop initially serves to move the 
cursor on the screen in response to the arrow keys. Once the user 
presses B , however, the loop serves to extend or contract the 
marked block by calling the function MarkBloek. When the pro¬ 
gram detects the Escape key, it calls CopyBlock to copy the cur¬ 
rently marked block into the shared memory segment, and then 
terminates the pop-up session by calling VioEndPopUp. 

9. MarkBloek marks a block by first calling VioWrtNAttr to reduce 
all video attributes on the screen to white against a black back¬ 
ground; it then calls this same function to reverse the video attrib¬ 
utes (black against a white background) within the marked block. 

10. CopyBlock uses the function VioReadCharStr to read all 
characters—row by row—from the marked block directly into the 
shared memory segment. When this function has completed copy¬ 
ing the block, it writes the number of characters copied and the 
length of each row into fields reserved for this information within 
the shared segment. 

11. If the main monitor loop detects the Alt-P hotkey, it calls the 
Paste function, which uses DosMonWrite to insert all characters 
currently contained in the shared segment directly into the key¬ 
board data stream. Note that Paste inserts a special data packet 
for a carriage-return character (struct keypacket CarriageRetura) 
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at the end of each row (remember that both the total buffer length 
and the row length are stored within the shared segment). 

12. If an error is encountered within the monitor program, the func¬ 
tion ErrorQuit is called, which uses the pop-up mechanism to 
display error information, and then terminates the process. 


The Keyboard Data Packet 

Processing the stream of character packets passed through the chain of 
monitors is not equivalent to reading a series of keys by calling KbdCharln. 
KbdCharln simply returns the next key that has been placed in the key¬ 
board buffer. The device driver, however, sends a packet through the moni¬ 
tor chain almost every time a key is either pressed or released. Accordingly, 
the number of keyboard packets processed by monitors is greater than the 
number of keys that are ultimately placed in the keyboard buffer. For 
example, if the user presses the A key, two packets are generated (one for 
pressing the key and one for releasing it), but only one character is inserted 
into the keyboard buffer. Also, pressing and releasing a shift key (such as 
Shift or Alt) generates two packets that affect the interpretation of subse¬ 
quent keystrokes but do not result in entries into the keyboard buffer 
(except in raw mode with the shift report option on; see Chapter 9). 

When the monitor program tests for its hotkeys, it discards character 
packets that are generated by key releases (otherwise, each hotkey would be 
acted upon twice). Keyboard data packets indicate whether the key has been 
pressed or released. A keyboard data packet is 14 bytes long, and has the 
following format, expressed as a C structure: 

struct KeyPacket 

{ 

unsigned int MonFlags; 

KBDKEYINFO Data; 
unsigned int DevFlags; 

}; 

MoeFIags is the one-word monitor flag that is placed at the beginning of 
data packets for any device. For the keyboard, this flag has the following 
structure: 

BITS MEANING 

0-7 Original hardware scan code for 

key 

8-9 Not used by keyboard 


/* Keyboard monitor flags. */ 

/* Keyboard data. */ 

/* Keyboard device flags. */ 
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10 Flush request 
11-15 Reserved 

When bit 10 (flush request) is set, the monitor should flush any internal 
buffers containing packets that have not yet been written (the example pro¬ 
gram does not buffer packets and thus does not test this bit). Note that if 
you insert additional packets into the data stream, the MooFIags word 
must be set to 0 (the example monitor in Figure 11.4 sets these bits to 0 in the 
packets that are inserted when the program performs its paste operation). 

The Data field is a 10-byte structure that has the same format as the data 
returned by KbdCharln; therefore, the example program simply uses the 
structure KBDKEYINFO that is defined for KbdCharln in an OS/2 
header file. KBDKEYINFO has the following format: 

struct 

{ 

unsigned char chChar; 
unsigned char chScan; 
unsigned char fbStatus; 
unsigned char bNIsShift; 
unsigned char fsState; 
unsigned char time; 

} 

KBDKEYINFO; 

See the descriptions of these fields in Appendix B (under KbdCharln). 
Finally, BevFlags is a one-word keyboard-device driver flag, which has the 
following format: 

BITS MEANING 

0-5 A special action code. If these bits are set to 0, the packet contains a 
normal character that will be entered into the keyboard buffer; 
otherwise, they indicate some special action that might have to be 
taken to process the keystroke (such as a shift key, a break key, or the 
PrtSc key). Note that the keystroke can be fully identified using the 
Data structure described above; these bits simply supply additional 
information for certain keystrokes. 

6 Key released. If this bit is set, the packet has been generated by the 
release of a key. 

7 Second byte of a 2-byte scan code. 
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8 A typamatic repetition of a shift key (which will be ignored by the 
device driver). 

9 Second byte of an accented 2-byte character. 

10-13 Reserved (must be 0). 

14-15 These bits are available for sending messages from one monitor to 
another. 

















































































CHAPTER 

Introduction to 
the Presentation 
Manager 

This book began by describing how to convert a text-mode MS-DOS 
program to run under the protected mode of OS/2. It then introduced 
many of the advanced features of OS/2 that go far beyond the facili¬ 
ties provided by MS-DOS. It should be obvious from the discussion of 
these advanced features that relatively simple MS-DOS-style pro¬ 
grams realize only a small portion of the potential of OS/2, and that 
OS/2 is an ideal environment for developing complex and sophisti¬ 
cated applications. Before launching a major software enhancement 
project or a new development effort, however, you must make a criti¬ 
cal decision: whether to write a standard kernel application using the 
techniques discussed in the previous chapters, or whether to write spe¬ 
cifically for the OS/2 Presentation Manager. This chapter introduces 
the Presentation Manager and is written to help you make this impor¬ 
tant decision. 
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PRESENTATION 

MANAGER 

PROGRAMS 


As mentioned in Chapter 1, the Presentation Manager is included with 
OS/2 beginning with version 1.1. The Presentation Manager provides a 
graphics interface that is quite similar to that offered by Microsoft Win¬ 
dows version 2.0 and later. The user can run multiple simultaneous applica¬ 
tions within windows on the screen, and can control these applications 
through a uniform set of keyboard and mouse commands. Unlike the com¬ 
mand line environment of a normal protected mode screen group, most of 
the program objects are immediately visible on the screen and can be 
directly accessed through menus, dialog boxes, keyboard commands, and 
mouse actions. 

The Presentation Manager is an operating-system extension; it is a high- 
level set of programming facilities implemented as a collection of dynamic- 
link libraries. These facilities allow you to develop programs that can 
run within one or more windows on the screen, can communicate intimately 
with other programs, and can take advantage of a uniform and sophisti¬ 
cated graphics interface. 

The topic of using and programming under the Presentation Manager is 
complex and could fill many volumes; this chapter provides only a brief 
introduction, emphasizing the advantages of the Presentation Manager and 
the new concepts involved when using or programming under this environ¬ 
ment. The chapter begins by describing the different categories of programs 
that can run in a system with the Presentation Manager installed. Next, it 
describes the user and the programmer interfaces, and finally summarizes 
the unique architecture of a Presentation Manager program. 


In systems that include the Presentation Manager, the user interface shell 
(described in the next section) replaces the standard OS/2 command line 
and the text-mode session manager described in previous chapters. When 
the system is started, this shell occupies the initial screen, and allows you 
either to start a new program (through the Startup Window) or to switch to 
any program that is currently running (through the Task Manager). Note 
that the Presentation Manager itself, as well as all programs that run within 
one of its windows, are contained in a single screen group. The user inter¬ 
face shell can run programs within the Presentation Manager screen group, 
as well as programs in other screen groups. Programs that can be executed 
under this shell fall into the following four general categories: 

1. MS-DOS applications running in the real mode screen group 

2. Protected mode kernel applications running in separate screen 
groups from that occupied by the Presentation Manager 
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3. Kernel applications that run within a window of the Presentation 
Manager, but do not use any of the special features afforded by the 
Presentation Manager programming interface 

4. Applications that are written specifically for the Presentation 
Manager 

Note that programs within the second and third categories are commonly 
described as protected mode kernel applications. 

The second category consists of programs that cannot run within a win¬ 
dow of the Presentation Manager. These are programs that perform one or 
more of the following actions: 

♦ Write directly to the logical or physical video buffers; the Vio 
functions that allow you to directly manipulate these buffers are 
described in Chapter 9 

♦ Switch video modes through the VioSetMode function or by 
directly programming the video controller registers through I/O 
privileged routines 

♦ Alter the video state by calling VioSetState or by directly program¬ 
ming the video controller registers through I/O privileged routines 

♦ Replace video, keyboard, or mouse functions (through VioRegis- 
ter, KbdRegister, or MouRegister) 

♦ Install a keyboard or mouse monitor (described in Chapter 11) 

Note that kernel graphics programs need to perform one or more of these 
prohibited actions and are therefore excluded from running within a Pre¬ 
sentation Manager window. 

In general, text-mode programs that perform I/O through the standard 
OS/2 Vio , Kbd, and Mou functions can run either within a window of the 
Presentation Manager, or within a separate screen group. These programs 
constitute the third category listed above. Although programs in this cate¬ 
gory can be run within a window that is opened and controlled by the user, 
they cannot take advantage of the extensive set of functions available for 
programs written specifically for the Presentation Manager. 

The fourth category comprises the true Presentation Manager applica¬ 
tions that conform to the exacting program architecture described in this 
chapter, and that are free to use the extensive set of facilities provided by the 
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Presentation Manager programming interface. Among the many features 
available to these specially written programs are the following: 

♦ All of the features that can be employed by normal protected 
mode applications, such as the large virtual memory space, 
multitasking, and interprocess communication 

♦ A set of functions for creating and managing multiple windows 
on the screen 

♦ Functions for performing keyboard, screen, mouse, and other 
character-device I/O 

♦ Functions for managing menus, scroll bars, and dialog boxes 

♦ Functions for directly controlling features of the Task Manager 
(described in this chapter) 

♦ Flexible handling of text output and fonts 

♦ An extensive and sophisticated collection of graphics primitives 

The Kernel vs. the Presentation Manager 

There are several advantages to writing a standard OS/2 kernel application. 
First, the kernel provides a more familiar programming environment than 
the Presentation Manager; it is especially suited for developing applications 
in the C language. Also, text-mode kernel programs run faster than equiva¬ 
lent Presentation Manager programs, since text modes are inherently faster 
than graphics modes. (All applications that run within a Presentation Man¬ 
ager window operate in a graphics mode—even those that produce simple 
text output.) 

Another advantage of the kernel environment is that it provides maxi¬ 
mum flexibility for designing a unique user interface. The I/O routines pro¬ 
vided by the kernel operate at a relatively low level; an interactive program 
typically requires a set of higher-level functions for managing the user inter¬ 
face (such as routines for managing windows, displaying menus, and 
accepting formatted input). Under the OS/2 kernel, you have the freedom 
to write your own interface routines or to choose a package written by a 
third party. As seen in Chapter 10, routine packages can be written as 
dynamic-link libraries and can be shared by all running programs. 

Finally, if you avoid the prohibited actions listed above and discussed in 
Chapter 9, a kernel-mode application can run within a window of the Pre¬ 
sentation Manager. The user can view several of these applications on the 
same screen, and can manipulate the windows that contain the programs 
using a basic set of Presentation Manager commands. 
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Accordingly, the OS/2 kernel would be ideal for developing text-mode 
programs that are characterized by their high speed or unique user interface 
(for example, a word processing application). Furthermore, the familiarity 
of the kernel programming interface facilitates the process of rapidly port¬ 
ing such applications from the MS-DOS environment. Also, writing or 
porting an application to the OS/2 kernel can serve as the first step in devel¬ 
oping a program that will ultimately be transformed into a Presentation 
Manager application. 

In contrast, the Presentation Manager provides a complete set of high- 
level programming facilities (some of which were listed in the previous sec¬ 
tion). The first obvious advantage of the Presentation Manager is that by 
writing under this environment, you can concentrate on the main logic of 
your program and are freed from developing your own user interface 
routines. Furthermore, the user interface provided by the Presentation 
Manager is uniform across all applications; such a standard interface frees 
the user from the need to learn a new set of commands for each program 
and also facilitates communication among individual applications. This 
interface is also in conformance with IBM's SAA (Systems Application 
Architecture) standard, which means that the interface should also become 
common on larger computer systems. 

The Presentation Manager is especially valuable for developing graphics 
programs (remember that kernel applications cannot use graphics modes if 
they are to run within a window). The Presentation Manager provides a vast 
set of graphics primitives, known as the GPI (graphics programming inter¬ 
face). These functions can be used to create graphics output both on the 
screen and on devices such as printers and plotters. 

However, even programs that are essentially textual, such as word pro¬ 
cessors, can benefit from being run in the graphics mode provided by the 
Presentation Manager. Using graphics, text output can be displayed in a 
variety of fonts to produce a screen image that closely resembles the final 
printed copy. Also, a graphics display mode enables the Presentation Man¬ 
ager to create the detailed icons and window elements that allow the user to 
control the application. In general, a graphics screen can communicate a 
higher density of information than a text mode screen, regardless of the 
type of application. 

Another important benefit of the Presentation Manager is that both the 
I/O routines and the graphics primitives are device-independent. A prop¬ 
erly written program can produce output on any monitor, printer, plotter, or 
other device that is supported by the Presentation Manager. A specific 
device gains the support of OS/2 by installing an appropriate driver. (Pre¬ 
sentation Manager device drivers are implemented as dynamic-link 
libraries, and are distinct from the standard OS/2 device drivers discussed 
in Chapter 2.) Therefore, a Presentation Manager program will run without 
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modification on all new devices, provided that a suitable device driver is 
supplied (and it is likely that most new output devices will be accompanied 
with drivers for the Presentation Manager). 


THE USER 

INTERFACE 

SHELL 


♦ The File Cabinet, which allows you to view and manipulate disk 
drives, directories, and files. This facility additionally contains the 
Startup Window, which is used to load and run programs. Note 
that programs can also be started using a command line option. 

$ The Task Manager, which allows you to select and switch to a 
running program. If the program is running within a window, this 
window is brought to the top of the stack of overlapping windows 
and is made the active window (the active window is the one that is 
currently interacting with the user). If the program is not running 
in a Presentation Manager window, the Task Manager switches 
into the screen group that contains the program. 

♦ The Startup Editor, which allows you to add or modify entries that 
appear in the Startup Window. 

♦ The Control Panel, which is used to set system parameters such as 
the screen colors. 

§ Printer Services, which is used to control character output devices 
other than the screen. 

♦ A help facility, which supplies information on using the shell and is 
accessed through the FI key or by clicking the mouse while the 
pointer is on the FI -Help choice within the menu bar. 

♦ The user interface shell provides a cut-and-paste utility, which 
stores character or graphics data in the clipboard and can be 
accessed either through the system menu or an application's menu 
bar (described later in this section). 

♦ The user interface shell also allows you to control the position and 
size of all application windows on the screen. 


When a system including the Presentation Manager is first started, the user 
interface shell occupies the initial screen. This shell replaces both the simple 
OS/2 command line interface provided by CMD.EXE and the text mode 
session manager. As mentioned in the preceding section, the user interface 
shell can be used to manage Presentation Manager applications as well as 
programs that must run in separate screen groups. The following are the 
chief elements of this shell: 
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Each Presentation Manager application can run within one or more win¬ 
dows on the screen. These windows are organized in an overlapping style, 
giving the screen a “messy desk” appearance. The user interface shell inter¬ 
cepts certain keystrokes and mouse commands that allow the user to bring a 
specific window to the top of the stack and begin interacting with the pro¬ 
gram running within the window. 

A typical application window does not consist of a simple border, but 
rather contains several distinct elements that provide an important medium 
for user interaction (each of these elements is actually a distinct window that 
is a child of the basic frame window). The following are the elements 
that may be contained within a typical application window. These elements 
are illustrated in Figure 12.1. 

♦ A surrounding border, which can be used to change the size of the 
window. 

♦ A title bar at the top of the window, which is highlighted when the 
window is active, can be used to move the window, and usually 
displays the name of the application. 


SYSTEM ICON 
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BORDER 
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FIGURE 12.1: Elements of a typical Presentation Manager application window 
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♦ Vertical and horizontal scroll bars, which are used to move the 
data that appears in the window. 

♦ A horizontal menu bar (or action bar) near the top of the window, 
which allows the user to issue commands or to select pull-down 
menus that offer additional choices. 

♦ A system icon, which can be used to activate a menu of system 
commands for performing such functions as moving or changing 
the size of the window, copying data from one window to another, 
or closing the application. 

♦ Maximize and minimize icons, which allow the user to change a 
window to its maximum or minimum size. 

♦ A large central portion, which is used to display the program data 
and is termed the client area. 

In addition to these static window elements, the application may elicit 
additional information from the user by using a dialog box , which is a spe¬ 
cial temporary window that displays information and receives user input. 


THE 

PROGRAMMER 

INTERFACE 


♦ Window management. These functions allow you to create and 
manage one or more windows. Presentation Manager windows are 
the primary programming objects through which a procedure 
communicates with the user, with the system, and with other 
procedures. 

♦ Input and message handling. This set of functions handles the 
messages that are passed to a window procedure. These messages 
are generated by keyboard and mouse input, by the system, and by 
other procedures or applications. The next section describes the 
message-based architecture of Presentation Manager applications. 

♦ Alphanumeric output. These services are termed advanced Vio 
functions , and can be used to rapidly display character-based data 
within a window or send characters to a device, employing a vari¬ 
ety of fonts. 


The Presentation Manager application program interface (API) provides 
the following categories of functions. Note that an application cannot call 
these functions unless it conforms to the program structure described in the 
next section. 
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$ Graphics output. This large set of functions forms the GPI (graph¬ 
ics programming interface) and is used to display graphics infor¬ 
mation on the screen or send this data to other output devices. 

♦ Bitmap management. Bitmaps are blocks of graphics data, which 
can be stored in memory or in disk files, and can be used to rap¬ 
idly manipulate and transfer graphics information. 

♦ User interface control. These functions manage the communica¬ 
tion of information between the program and the user; specifically, 
they support menu bars, pull-down menus, and dialog boxes. 

♦ Shell control. These functions allow an application to directly 
access some of the services of the user interface shell described in 
the previous section. For example, an application can add an entry 
to the list of running programs maintained by the Task Manager. 


THE 

ANATOMY 
OF A 

PRESENTATION 

MANAGER 

PROGRAM 


An application that uses the services of the Presentation Manager API must 
conform to a specific program architecture. This section discusses two 
aspects of this architecture: the required function-calling sequence and the 
processing of messages. 

First, an OS/2 program cannot simply call the functions of the Presenta¬ 
tion Manager in an arbitrary order; rather, you must call these functions in 
a specific sequence, and you must frequently save a handle returned by one 
function and use this handle to make subsequent function calls. Even a triv¬ 
ial program that writes “hello world” to the screen requires an entire 
sequence of function calls (the specific function calls will be described later 
in this section). These calls allow the Presentation Manager to perform ini¬ 
tializations and to collect information relevant to the particular process, 
thread, window, or other object using the services. The handles that are 
returned from functions and passed to other functions serve to identify the 
user of the service or resource. 

Second, the basic task that must be performed by a Presentation Man¬ 
ager program is to receive and process messages. This message-based archi¬ 
tecture is quite different from the structure of most conventional programs. 
Conventional programs typically initiate a sequence of actions, and pause 
for user input at well-defined points in the code where the program requires 
input. A message-based Presentation Manager program, however, nor¬ 
mally waits in an idle state until it receives a message; it then performs the 
action specified by the message, and when this task is completed it waits to 
receive another message. The heart of a Presentation Manager program is 
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therefore a loop that repeatedly waits for, receives, and dispatches mes¬ 
sages. (Note that this basic structure can become considerably more com¬ 
plex in a multiple-thread Presentation Manager application.) 

A message-based architecture makes sense in a highly structured envi¬ 
ronment such as the Presentation Manager, in which separate programs are 
run simultaneously and intimately share resources (notably, the screen, key¬ 
board, and mouse). To work harmoniously in such an environment, a pro¬ 
gram must respond quickly and appropriately to the actions of the system, 
the user, and other applications. The program is informed of all external 
events that may require it to perform some action through messages. 

Figure 12.2 illustrates the message-based architecture of a Presentation 
Manager program. The basic program object that receives all messages is 
the window; messages are therefore said to be sent “to a window.” In more 
conventional terms, a program creates a window and associates a procedure 
with this window. When a message is subsequently sent to this window, the 
system calls the associated procedure, passing a code for the specific mes¬ 
sage as well as other information. In Figure 12.2, the thread that creates the 
window is termed the window thread , and the procedure that processes 
messages for this window is labeled the window procedure . When the win¬ 
dow procedure receives control, it performs an appropriate action based 
upon the message it receives, and then returns to the system. 

As shown in Figure 12.2, the system sends a message to a window in 
response to a variety of events. For example, the system sends a message 
when it receives keyboard or mouse input from the user, when the user has 
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FIGURE 12.2: The message-based architecture of a Presentation Manager program 
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rearranged the windows on the screen and the window needs to be redrawn, 
or when another procedure has explicitly sent a message to the window 
(through the WinSendMsg or WinPostMsg function). Note that the system 
can call the window procedure directly, or it can place the message in a 
queue that has been created by the window thread. The main loop within 
the window thread must extract messages that have been placed in the queue 
(using WinGetMsg) and then dispatch these messages (using WinDispatch- 
Msg). When a message is dispatched, the system calls the window proce¬ 
dure, passing it the code for the message as well as additional information. 

The following is the sequence of operations that a Presentation Manager 
program must perform simply to create a window and display a string on 
the screen. These operations constitute a minimal Presentation Manager 
program and serve to illustrate the required function-calling sequence, as 
well as the message-based architecture. The following operations should be 
performed from the main body of the program (function main if you are 
programming in C): 

1. Invoke the Winlnitialize function to initialize the Presentation 
Manager system for the calling process, and to obtain an anchor 
block handle that must be passed to all subsequent Presentation 
Manager functions to identify this process. 

2. Create a message queue by calling WinCreateMsgQueue. The 
system will place in this queue messages addressed to the window 
that will subsequently be created. 

3. Call WinRegisterClass to associate a window procedure with a 
class name (and to specify certain options regarding the manner in 
which the procedure is called). The window procedure is the func¬ 
tion that will be called whenever the system dispatches a message 
to the window. The reason for establishing this association will 
become evident in the following steps. 

4. Call WinCreateStdWindow to create a standard window on the 
screen. (Note that a standard window is actually a collection of 
several windows, typically including a frame window and windows 
for most of the basic elements listed in Figure 12.1, such as the 
border, title bar, and client area.) You must pass this function a set 
of parameters that specify the style of the window. You also pass 
the class name mentioned in step 3. 

Steps 3 and 4 have now established a link between the client window and 
the window procedure; the system now knows the procedure that must be 
called whenever a message is dispatched to the client window. 
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5. The program should now enter the main loop that repeatedly calls 
WinGetMsg to extract a message from the message queue, and 
then calls WinDispatchMsg to dispatch this message. Note that a 
message is addressed to a specific window. When you call Win¬ 
DispatchMsg, the system sends the message to the procedure asso¬ 
ciated with the addressed window; therefore, the system will now 
send any messages addressed to the client window to the window 
procedure within your program, the address of which was speci¬ 
fied in step 3. Note that messages sent to any other windows (such 
as the frame window or the border window) will be sent to default 
system procedures for these windows (since in step 3 you registered 
a procedure only for the client window). 

6. When the user asks the system to terminate the program, the 
WinGetMsg function returns a value of 0. At this point, the pro¬ 
gram should exit from the loop and terminate the program. Before 
exiting, however, the program should call WinDestroyWindow to 
release the window, WinDestroyMsgQueue to release the message 
queue, and WinTerminate to sever its ties with the Presentation 
Manager. 

Once the program has made the required initial function calls and has 
entered its main message-processing loop, all further action takes place 
within the window procedure. In C, the window procedure should be writ¬ 
ten as a separate function, and can consist of a single switch statement that 
performs the appropriate tasks based upon the message it is passed. All 
messages that are not processed within this procedure should be passed 
back to the system for default processing, by calling WinBefWindowProc. 

How can the window procedure be used to display a string on the screen? 
The system sends a specific message to the window whenever the screen data 
must be drawn. This message is sent when the window is first created and 
whenever a portion of the window has been obscured (for example, by an 
overlapping window) and needs to be displayed again. Thus, if the proce¬ 
dure writes the string to the window whenever it receives this message, the 
string will appear when the window is first created, and will reappear when¬ 
ever the window becomes visible after being obscured. 

The Presentation Manager provides a variety of functions for displaying 
textual data on the screen. In general, you must first call a function to 
obtain access to the screen, then call the required services for displaying the 
data, and finally call a function to relinquish access. For example, you can 
call WinBeginPaint to gain access to the screen, WinDrawText to display a 
string, and finally WinEndPaint to yield access. 
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If you compile a Presentation Manager program written in Microsoft C 
that contains a window procedure, you should use two command line 
options in addition to those described in previous chapters for compiling 
normal protected mode programs. First, specify the - Gs option to disable 
calls to the stack-checking routine, which is incompatible with the Presenta¬ 
tion Manager. Second, specify the - Gw option, which causes the window 
procedure to save and restore the contents of the data segment (DS) register 
(this step is necessary because the procedure is called from a dynamic-link 
library, which uses a separate data segment). 

Finally, when you link a Presentation Manager program, you must gen¬ 
erally supply a definition (.DEF) file (these files are discussed in Chapters 4 
and 10). This file generally contains a HEAPSIZE command to specify the 
program heap size (for example, 2048 kilobytes), and a STACKS1ZE com¬ 
mand giving the required stack size (for example, 4096). The definition file 
must also contain an EXPORTS statement that lists the names of all win¬ 
dow procedures. 
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APPENDIX A 


Glossary 


This glossary defines many of the terms you may encounter while 
working with OS/2. If a term has a special meaning within the context 
of OS/2, this definition is given rather than the general significance of 
the word. Note also that OS/2 is a new and rapidly evolving operating 
system; you may therefore discover inconsistencies in the terminology 
from one source to another, as well as general changes over time in the 
usage of these technical terms. 
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alias 

A segment descriptor that references the same memory segment as another 
descriptor. 

anchor block handle 

A numeric value that identifies a process to the Presentation Manager 
(returned by Winlnitialize). 

ANSI 

American National Standards Institute. ANSI codes are a set of escape 
sequences that can be embedded in video output to control the console. 

API 

The application program interface, which is a set of services provided by the 
operating system for application programs. 

argument 

A value passed to an operating-system command from the command line, 
or passed to a function within a program; same as parameter. 

ASCII 

American Standard Code for Information Interchange; the encoding 
scheme that represents the character set used by microcomputers. 

asynchronous 

Two or more procedures are said to be asynchronous if they occur concur¬ 
rently, but without timing relationships. Specifically, if two procedures are 
asynchronous, when a particular instruction is executed in one procedure it 
is impossible to predict which instruction is currently being executed in the 
other procedure. See also synchronous . 

atomic 

Indivisible; describes a sequence of processor operations that cannot be inter¬ 
rupted, typically those required to execute a single machine instruction. 

background programs 

Programs executed through the RUN configuration command, the 
DETACH command line instruction, or from a parent program. These pro¬ 
grams are not attached to a screen group and do not normally interact with 
the user. 
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batch file 

A file containing a sequence of instructions to be executed by a command 
interpreter. 

BIOS 

Basic input/output system; the low-level code that controls I/O devices, 
normally implemented in the read-only memory (ROM) supplied with the 
computer. 

block 

To wait for an event without consuming processor cycles. For example, a 
thread can block while waiting for a resource, and it will be released by the 
operating system when the resource is available. 

boot disk 

The disk drive that contains the code used to initialize the computer and 
load the operating system when the system is first reset or powered on. 

bound program 

Same as dual-mode program . 

buffer 

An area in memory used to temporarily store data that is read or written in 
blocks; increases the efficiency of data transfer operations. 

busy waiting 

Creating a delay, or waiting for a computer event, by executing a non¬ 
productive program loop. 

cache 

A high-speed storage area used to improve the efficiency of accesses to a 
slower-speed storage medium. For example, temporarily storing data in 
a disk cache in random access memory can reduce the number of accesses 
required to transfer contiguous blocks of disk data. 

call gate 

A special type of segment descriptor that allows a process to call a sub¬ 
routine contained within a higher-privileged segment. 
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CGA 

Color graphics adapter; a standard video controller that provides graphics 
with a maximum resolution of 640 by 200 pixels. 

child process 

A process started by another process (its parent), 
code page 

A table used to define a character set used by the system, 
command processor 

A program that executes operating-system commands. By default, the 
command processor for the protected mode is CMD.EXE, and for the real 
mode is COMMAND. COM. 

compatibility box 

The OS/2 screen group for running real mode MS-DOS programs, 
concurrency 

The simultaneous execution of two or more sequences of machine instruc¬ 
tions; see also multitasking . 

cooked mode 

A state in which a character-device driver processes certain characters 
within the data stream as control codes. See also raw mode . 

CPU 

The central processing unit, or the microprocessor belonging to a micro¬ 
computer. 

critical section 

A body of code accessing a resource that cannot be shared by more than one 
simultaneous task. 

deadlock 

A situation in which one or more tasks is blocked, waiting for an event that 
cannot occur. 
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descriptor 

A structure in memory maintained by the operating system, which contains 
the physical address of a segment as well as other information regarding this 
segment. 

descriptor table 

A table in memory containing a collection of segment descriptors, 
device driver 

A program that translates operating-system commands into the device¬ 
specific code necessary to control a given device. 

device interrupt routing 
See interrupt routine. 

dialog box 

A temporary window under the Presentation Manager that displays infor¬ 
mation and obtains user input. 

dual-mode program 

A specially prepared program that can run under MS-DOS, in the compati¬ 
bility box of OS/2, or within a protected mode screen group; the same as a 
bound program . 

dynamic-link library 

A module of functions stored in an executable file (with the .DLL exten¬ 
sion) and linked to the application that calls the functions either at load¬ 
time or at run-time. 

EGA 

Enhanced graphics adapter; a standard video controller that provides 
graphics with a maximum resolution of 640 by 350 pixels. 


event-driven process 

A process that blocks until it is activated by an external event. 
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exception 

A processor error or other internal condition that generates an interrupt 
and transfers control to a software routine designed to handle the event. 

expanded memory 

Memory available to real mode programs above the normal 640-kilobyte 
limit. This memory is contained on special adapter cards and is accessed 
through a hardware paging mechanism. 

Extended Edition 

A version of OS/2 that contains operating-system extensions such as a 
database manager and a communications manager. 

extended memory 

Memory contained in 80286/80386 machines at addresses above 1 mega¬ 
byte. This memory space can be accessed directly only in protected mode. 


Family API 

A subset of the full OS/2 API functions that can be called by dual-mode 
programs when they are running in real mode. 

far address 

An address containing both a 16-bit segment selector (in the protected 
mode, or the address in the real mode) and a 16-bit offset within this seg¬ 
ment. See also near address. 

font 

A collection of bitmaps defining the shape of each character within a given 
character set. 

gigabyte 

2 30 , or approximately one billion, bytes, 
global descriptor table 

A table maintained in memory containing the descriptors for segments that 
can be accessed by all processes; see also local descriptor table. 
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handle 

A numeric value returned by many OS/2 functions that is used to identify 
the owner of a resource (such as an open file) when subsequent function 
calls are made. 

hotkey 

The keystroke that activates a background program (under OS/2, usually a 
monitor). 

huge memory allocation 

A block of allocated memory consisting of more than one segment. The 
segments need not be contiguous in memory, but the selectors for these seg¬ 
ments differ numerically by a constant amount. 

import library 

A library file that resolves references to dynamic-link functions by supply¬ 
ing records that contain the module name and entry point for the function, 
but not the actual code. 

interrupt 

A software-, hardware-, or processor-generated event that passes control to 
a routine in memory that provides a service or handles a condition. 


interrupt routine 

The device driver entry point invoked by hardware interrupts that are gen¬ 
erated by the associated device; see also strategy routine. 

I/O privilege 

Permission granted to a specific code segment to issue direct port 1/O 
instructions or to enable or disable hardware interrupts. 

kernel 

The core operating-system code that operates at the highest privilege level; 
also, the portion of the API exclusive of the Presentation Manager and 
other operating-system extensions. 

kilobyte 

2 10 , or 1024, bytes. 
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local descriptor table 

A table maintained in memory containing the descriptors for segments that 
can be accessed by a specific process; see also global descriptor table . 

megabyte 

2 20 , or approximately 1 million, bytes. 

monitor 

An OS/2 program tnat processes the stream of characters passing to or 
from a character device. 

multiprocessing 

Simultaneous execution of code by more than one processor in a single 
computer. 

multitasking 

Refers to the simultaneous execution of more than one sequence of machine 
instructions. 

multiuser 

Refers to a single computer connected to more than one terminal, which 
allows several users to share the same processor. Note that OS/2 is not a 
multiuser system. 

near address 

An address consisting of only a 16-bit offset. See also far address . 

overcommitment (of memory) 

Allocation of more memory than is physically present in the machine; 
accomplished by swapping segments between memory and secondary stor¬ 
age on a disk. 

parameter 

A value passed to an operating-system command from the command line, 
or passed to a function within a program; same as argument . 

parent process 

A process that starts another process (its child). 
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path 

The full specification of the location and name of a disk file. 

pipe 

A form of interprocess communication that allows two related processes to 
exchange a serial stream of data. 

pixel 

Picture element; smallest unit on the screen that can be controlled (turned 
on or off, or assigned a color or intensity). 

poll 

To test for the occurrence of a specific event; for example, an inefficient 
program might repeatedly poll for the arrival of a character rather than 
blocking. 

port 

An input/output address that can be used to control a device. 

preempt 

To take control away from a particular task in a multitasking system (rather 
than letting the task voluntarily yield control). OS/2 is a preemptive multi¬ 
tasking system. 

Presentation Manager 

An operating-system extension provided with OS/2 versions 1.1 and later. 
The Presentation Manager provides a windowed, graphics interface similar 
to Microsoft Windows. 

priority 

A value assigned to each thread in the system that allows the scheduler to 
determine which thread among those ready to run should be dispatched. 

privilege 

The set of permissions associated with a particular segment. There are four 
privilege levels, numbered from 0 (highest privilege level, reserved for the 
operating system) to 3 (lowest privilege level, for application programs). 
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process 

A single instance of the execution of a program, 
program 

A collection of code and data stored in an executable file and loaded into 
memory at run-time. 

protect 

To prevent a given process from corrupting other processes in a multitask¬ 
ing system; OS/2 uses the hardware protection mechanisms provided by the 
80286 processor. 

protected mode 

A processor state of the 80286/80386 processors that allows the operating 
system to safely run multiple tasks and provide virtual memory; same as 
virtual mode . 

queue 

An ordered collection of messages that have been sent from one or more 
processes to a single receiving process. 

RAIVi 

Random access memory; the randomly addressable, volatile main memory 
used to store programs and data. 

raw mode 

A state in which a character-device driver passes all characters as literal 
values, and does not respond to control codes embedded in the data stream. 

real mode 

A processor state of the 80286/80386 processors that emulates the opera¬ 
tion of the 8086/8088 processors. 

real mode screen group 
Same as compatibility box . 

reentrant 

A segment of code is termed reentrant if it can be executed more than once 
at the same time. 
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mm 

Read-only memory; nonvolatile memory supplied with microcomputers 
that normally contains code to control hardware devices. 

scan code 

A code emitted by the keyboard to indicate the specific key that has been 
pressed or released. 

scheduler 

The portion of the operating system that apportions CPU time among mul¬ 
tiple threads, and determines the priority of each thread. 

screen group 

A collection of processes that share a single virtual screen, keyboard, and 
mouse. 

segment 

A variable-length block of allocated memory together with a set of attrib¬ 
utes (such as the privilege level). 

selector 

A virtual address for a memory segment, which serves as an index into a 
table containing the actual physical address; the selector is loaded into a seg¬ 
ment register such as DS to address the corresponding segment. 

semaphore 

A software flag used to synchronize the activities of two or more threads of 
execution. 

serialize 

To ensure that a given resource can be accessed by only one thread at a time; 
access to a resource is typically serialized by means of a semaphore. 

server 

The process that owns a queue and receives the queue messages, 
session 

Same as a screen group . 
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session manager 

A system utility that manages switching among screen groups. 

shell 

A command processor, such as COMMAND.COM for real mode, or 
CMD.EXE for protected mode. 

spooler 

A background program that stores printer output in temporary files and 
prints these files in a given order. 

strategy routine 

The device driver entry point called by the operating system to request a 
device service; see also interrupt routine . 

subsystem 

A set of dynamic-link functions that control a common resource, such as 
the OS/2 video management functions that are named with the Vio prefix. 

swapping 

The temporary storage of memory segments on disk to make room for 
other segments. This mechanism is useful when memory is overcommitted. 

synchronous 

Two procedures are said to be synchronous if their actions occur in a spe¬ 
cific order. For example, if one procedure waits at a given point until a sec¬ 
ond procedure completes, these procedures are said to be synchronous. See 
also asynchronous. 

task 

A general term referring to one of the concurrent threads or processes of a 
multitasking system. 

thread 

The basic dispatchable entity under OS/2; the execution of a series of 
machine instructions within a program. 
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lime slice 

The period of time that the scheduler allows a thread to run before it grants 
CPU time to another thread of equal priority. 

TER 

A terminate-and-stay-resident program under MS-DOS or the DOS com¬ 
patibility box of OS/2. These programs remain loa.ded in memory while the 
user runs other applications in the foreground. 

lypamatic 

Refers to the automatic repeated generation of keystrokes when a key is 
held down. 

virtual memory 

The allocatable memory space in protected mode, which may exceed the 
amount of physical memory installed in the machine. Segments within this 
space may be temporarily swapped to a disk to make room for segments 
that are currently being referenced. 

virtual mode 

Same as protected mode. 

VGA 

Video graphics array; a standard video controller that normally provides a 
graphics resolution up to 640 by 480 pixels. 
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Summary of the 
OS/2 API 


This appendix provides a brief summary of all the OS/2 API func¬ 
tions. Using this reference material in conjunction with the commen¬ 
taries in the chapters of this book should provide most of the 
information you need to develop OS/2 programs; if you feel the need 
for further details on a particular function, see the OS/2 Program¬ 
mer’s Reference cited in the Bibliography. 
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Unlike the reference material from Microsoft, the types of all functions 
and simple parameters are given as standard C data types. If you are already 
familiar with the C language, these declarations should be more under¬ 
standable and easier to use than those in the Microsoft references. Note, 
however, that the types of all parameters that are pointers to structures are 
given using the names of structures declared in the OS/2 header files. This 
appendix also fully defines each of these structures; for each structure field, 
the definitions provide the name of the field (the same as that in the stan¬ 
dard header file), the basic C data type, and a brief explanation. Accord¬ 
ingly, you do not need to define these structures within your program; 
rather, you can simply include the required portion of the standard header 
files and freely use the structure and field names that are given here. 
(Header definitions are incorporated in your program by defining the 
appropriate constants and including the file OS2.H, as explained in the sec¬ 
tion of Chapter 2 on The Application Program Interface.) For example, 
you can declare the necessary structure and call KbdCharln as follows: 


#define INCL_SUB 

/* Obtain definitions for subsystems. 

*/ 

include <OS2.H> 

KBDKEYINFO Key; 

/* Use type definition given in OS/2 

*/ 


/* header file and in Appendix B. 

*/ 

KbdCharln (&Key,0,0); 

if (Key.chChar = = 27) 

/* Reference field using name given 

*/ 


/* in OS/2 header file and Appendix B. 

*/ 


DosAllocHuge 

❖ Purpose 

Allocates a block of memory consisting of one or more 64-kilobyte segments. 

♦ Prototype 

unsigned int pascal far DosAllocHuge 
(unsigned int NumSeg, 

NtimSeg is the number of full 64-kilobyte segments to allocate, 
unsigned int PartialSeg, 


PartialSeg is the number of additional bytes in the last (partial) segment, 
which can be a value from 0 to 65,535. 
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unsigned short far *PtrSelector, 

PtrSelector is the address of the variable to receive the selector for the first 
segment in the allocated block. 

unsigned int MaxNumSeg, 

MaxNumSeg is the maximum number of 64-kilobyte blocks that can be 
allocated; you can enlarge the allocated block of memory by calling 
DosReallocHuge, up to the limit set by this variable. 

unsigned int AllocFlag); 

AIlocFlag is a shareable/discardable flag, which can be assigned one or 
more of the following values: 

Value Meaning 

0x0000 Nonshareable, nondiscardable segment 
0x0001 Segment shareable through DosGiveSeg 
0x0002 Segment shareable through DosGetSeg 
0x0004 Discardable segment 


DosAliocSeg 

♦ Purpose 

Allocates a memory segment. 

♦ Prototype 

unsigned int pascal far DosAliocSeg 
(unsigned int Size, 

Size is the number of bytes requested, 
unsigned short far * PtrSelector, 

PtrSelector is the address of the variable to receive the selector, 
unsigned int AllocFlags); 

AIlocFIags is a shareable/discardable flag, which can be assigned one or 
more of the following values: 

Value Meaning 

0x0000 Nonshareable, nondiscardable segment 
0x0001 Segment shareable through DosGiveSeg 
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0x0002 Segment shareable through DosGetSeg 
0x0004 Discardable segment 


DosAllooShrSeg 

♦ Purpose 

Allocates a shared memory segment, accepting a name and returning a 
selector. 

♦ Prototype 

unsigned int pascal far DosAllocShrSeg 
(unsigned int Size, 

Size is the number of bytes requested, 
char far *PtrSegmentName, 

PtrSegmentName is a pointer to a string to identify the segment, which 
must have the form \\sharemem\\/ztfme, where name is a unique identi¬ 
fier in the form of an OS/2 file name. 

unsigned short far *PtrSelector); 

PtrSelector is a pointer to a variable to receive the selector. 


OosBeep 

♦ Purpose 

Generates a tone from the speaker. 

♦ Prototype 

unsigned int pascal far DosBeep 
(unsigned int Frequency, 

Frequency is the frequency of the tone in hertz (cycles per second), from 
0x0025 to OxTFFF. 

unsigned int Duration); 

Duration is the duration of the tone in milliseconds. 


DosBufReset 


♦ Purpose 

Flushes the buffers for the given file by writing their contents to the disk or 
other appropriate device. Updates directory information. 
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♦ Prototype 

unsigned int pascal far DosBufReset 
(unsigned short FileHandle); 

FileHandle is the handle previously returned by DosOpen. If this parame¬ 
ter is set to OxFFFF, buffers are flushed for all open files. 


DosCaseMap 

♦ Purpose 

Converts the character values in a string to their equivalents in a given code 
page. 

♦ Prototype 

unsigned int pascal far DosCaseMap 
(unsigned int Length, 

Length is the length of the string. 

COUNTRYCODE far ‘PtrCountry, 

PtrCountry is a pointer to a COUNTRY CODE structure that contains the 
applicable country code and code-page identifier (see below). 

char far ‘String); 

String is a pointer to the string to be case-mapped. 

♦ Structures 

typedef struct _COUNTRYCODE 

{ 

unsigned int country; /* Country code to be used. */ 

unsigned int codepage; / * Code-page identifier to be used. */ 

} 

COUNTRYCODE; 


DosChdlr 

♦ Purpose 

Chooses a new default directory for a process and its children. 

♦ Prototype 

unsigned int pascal far DosChdir 
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(char far *PtrDirPath, 

PtrOirPath is a pointer to the path of the new default directory. 

unsigned long Reserved); 

Reserved must be zero. 


DosChgFilePtr 

♦ Purpose 

Moves a file pointer to a new position, relative to the current position or to 

the file’s beginning or end. 

♦ Prototype 

unsigned int pascal far DosChgFilePtr 
(unsigned short FileHandle, 

FileHandle is the handle previously returned by DosOpen. 
long Distance, 

Distance is a signed quantity indicating the number of bytes to move, 
unsigned int Method, 

Method specifies the starting position; it must have one of these values: 

Value Meaning 

0x0000 Start from beginning of file 

0x0001 Start from current position 

0x0002 Start from end of file 
unsigned long far *NewPtr); 

NewPtr is a pointer to a long variable to receive the new position. 


DosGLSAccess 

* Purpose 

Requests permission to disable and enable interrupts in a program’s IOPL 
segments. For use in assembly language programs. 

♦ Prototype 

unsigned int pascal far DosCLIAccess(void); 
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DosClose 

♦ Purpose 

Closes a file named by the handle parameter, writing out buffers and updat¬ 
ing directory information. 


♦ Prototype 

unsigned int pascal far DosClose 
(unsigned short FileHandle); 


FileHandle is the handle previously returned by DosOpen. 

DosCloseQueue 

♦ Purpose 

Closes a queue. If the calling process is the owner, the function removes any 
remaining elements. 


* Prototype 

unsigned int pascal far DosCloseQueue 
(unsigned short Queue); 


Queue is an identifier previously returned by DosCreateQueue or DosOpen- 
Queue. 

DosGloseSem 

♦ Purpose 

Closes a system semaphore to the calling process. Deletes the semaphore if 
no other processes have it open. 


♦ Prototype 

unsigned int pascal far DosCloseSem 
(void far *PtrSemHandle); 


PtrSemHandle is an identifier previously returned by DosCreateSem or 
DosOpenSem. 

DosCreateCS Allas 

❖ Purpose 

Returns a code-segment selector for the segment pointed to by the supplied 
data-segment selector, allowing execution of instructions in that segment. 




Programmer’s 
Guide to OS/2 
appB 


Not for use with shared memory segments, segments in huge memory 
blocks, or global data segments. 

♦ Prototype 

unsigned int pascal far DosCreateCSAIias 
(unsigned short DataSegment, 

BataSegment is the existing data-segment selector. 

unsigned short far *PtrCodeSegment); 

PtrCodeSegment is a pointer to a variable to receive the code-segment 
selector. 


DosCreateQueue 


♦ Purpose 

Creates and opens a queue. The calling process becomes its owner. 

♦ Prototype 

unsigned int pascal far DosCreateQueue 
(unsigned short far *PtrQueue, 

PtrQueue is a pointer to a variable to receive the queue handle, 
unsigned int QueueOrder, 

QueiieOrder is the order of in which queue elements are processed, which 
may have one of these values: 

Value Cleaning 

0x0000 First in, first out 
0x0001 Last in, first out 

0x0002 Remove by priorities given by writing processes 
char far *PtrQueueName); 

PtrQiieueName is a pointer to a string, which must have the form 
\\queues\Viame, where name must be unique and in the form of an OS/2 
file name. 


DosCreateSem 


♦ Purpose 

Creates a system semaphore, returning a handle. 
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* Prototype 

unsigned int pascal far DosCreateSem 
(unsigned int NoExclusive, 

NoExclusive specifies ownership of a semaphore,, It may have one of these 
values: 


Value Meaning 

0x0000 Calling process has exclusive ownership 
0x0001 Calling process does not have exclusive ownership 

void far * far *PtrSemHand!e, 

PtrSemHandle is the address of a pointer to a variable to receive the handle, 
char far *PtrSemaphoreName); 

PtrSemaptioreName is a pointer to the name of a semaphore, which must 
have the form \\sem\\name 9 where name must be unique and in the form 
of an OS/2 file name. 


DosCreateThread 

♦ Purpose 

Creates a new thread of execution. 

❖ Prototype 

unsigned int pascal far DosCreateThread 
(void (far *)PtrFunction(void), 

PtrFunction is a pointer to a function that will begin execution of the 
thread, which should be declared void far FunctionName(yo \&). 

unsigned int far *PtrThread, 

PtrThread is a pointer to a variable to receive the thread identifier, 
unsigned char far *PtrThreadStack); 

PtrThreadStack is a pointer to the base (highest address) of the thread 
stack. 


DosCWait 

♦ Purpose 

Blocks calling thread until descendant process or processes end. 
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♦ Prototype 

unsigned int pascal far DosCWait 
(unsigned int Scope, 

Scope specifies the number of processes to wait for, with one of these 
values: 


Value 

Meaning 

0x0000 

Wait only for specified process 

0x0001 

Wait for specified process and all its children 

unsigned int NoWait, 

No Walt specifies whether to wait for child processes, with one of these 
values: 

Value 

Meaning 

0x0000 

Wait for child process 

0x0001 

Do not wait; still allows process to obtain result code from a 
child that has ended 


RESULTCODES far *PtrResults, 


PtrResu&ts is a pointer to a RESULTCODES structure (described below), 
unsigned int far *PtrProcess, 

PtrProcess is a pointer to a variable to receive the process identifier of the 
ending process. 

unsigned int WaitProcess); 

WaitProcess is the PID of the child to wait for. If 0, thread waits for any 
child to end. 

♦ Structures 

typedef struct _RESULTCODES 

{ 

unsigned int codeTerminate; 
unsigned int codeResult; 

} 

RESULTCODES; 


/* System’s termination code; see below. */ 
/* Result code from process. */ 
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The termination code, codeTerminate, may assume one of these values: 


Value 

Meaning 

0x0000 

Normal exit 

0x0001 

Hard-error abort 

0x0002 

Trap operation 

0x0003 

Unintercepted DosKillProcess 


DosDelete 

♦ Purpose 

Deletes a file. 

❖ Prototype 

unsigned int pascal far DosDelete 
(char far *PtrFileName, 

PtrFileName is a valid file name. Wildcards are not accepted. 

unsigned long Reserved); 

Reserved must be zero. 


DosDevConflg 

♦ Purpose 

Returns information about attached devices. 

♦ Prototype 

unsigned int pascal far DosDevConfig 
(void far *PtrDevlnfo, 

PtrDevInfo is a pointer to the variable to receive device information, 
whose nature depends on the Item parameter. 

unsigned int Item, 

Item determines the nature of device information, according to these 
values: 


Value 

Meaning 

0x0000 

Number of printers 

0x0001 

Number of serial ports 
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0x0002 Number of floppy disk drives 
0x0003 Set if math coprocessor present; zero otherwise 
0x0004 PC submodel type: system submodel byte 
0x0005 PC model type: system model byte 
0x0006 Zero if primary display is monochrome; set otherwise 
unsigned int Reserved): 

Reserved must be zero. 


DosDevSOCtl 


♦ Purpose 

Enables direct control of various devices without resort to a device driver. 
The functions that are available through DosDevIOCtl are described indi¬ 
vidually in Appendix C. 

♦ Prototype 

unsigned int pascal far DosDevIOCtl 
(void far *PtrData, 

PtrData is a pointer to a data buffer; type is dependent on particular cate¬ 
gory and function. 

void far *PtrParnns, 

PtrParms is a pointer to a data buffer; type is dependent on particular cate¬ 
gory and function. 

unsigned int Function, 

Function is the function number under one of the categories of I/O control 
functions. 

unsigned int Category, 

Category is one of the categories of I/O control functions, 
unsigned int Device): 

Device is a handle previously returned by OosOpen, or else a standard 
device handle. 

♦ Structures 

Refer to Appendix C. 



Summary of the API 


DosDupHandSe 

♦ Purpose 

Duplicates an existing file handle; the new handle is fully equivalent to it. 

* Prototype 

unsigned int pascal far DosDupHandle 
(unsigned short OldHandle, 

OldHandle is a handle previously returned by DosOpen. 
unsigned short far *PtrNewHandle); 

PtrNewHandie is a pointer to a variable containing the desired file handle. If 
that value is OxFFFF, a new handle will be created and copied to the variable. 


DosEnterCritSec: 

♦ Purpose 

Suspends execution of other threads in a process. 

* Prototype 

void pascal far DosEnterCritSec(void); 


DosErrClass 

♦ Purpose 

Given an error code returned by a function, supplies an error classification 
and a recommended action. 

* Prototype 

unsigned int pascal far DosErrClass 
(unsigned int ErrorCode, 

ErrorCode is the return code to classify. 

unsigned int far *PtrClass, 

PtrClass is the error classification: 


Value 

Meaning 

0x0001 

Out of resources 

0x0002 

Temporary situation 

0x0003 

Authorization failure 
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0x0004 

Internal error 

0x0005 

Hardware failure 

0x0006 

System failure 

0x0007 

Application error 

0x0008 

Item not found 

0x0009 

Bad format; undocumented 

OxOOOA 

Locked; undocumented 

OxOOOB 

Incorrect media; CRC error 

OxOOOC 

Already in use; undocumented 

OxOOOD 

Unclassified error 

OxOOOE 

Cannot perform requested action 

OxOOOF 

Timeout 

unsigned intfar *PtrAction, 

PtrAction is the recommended action: 

Value 

Meaning 

0x0001 

Retry immediately 

0x0002 

Retry after delay 

0x0003 

Correct bad user input 

0x0004 

Abort: terminate in an orderly manner 

0x0005 

Panic: terminate immediately 

0x0006 

Ignore the error 

0x0007 

Retry after user intervention 

unsigned intfar *Ptrl_ocus); 

PtrLocus is the locus of the error: 

Value 

Meaning 

0x0001 

Unknown 

0x0002 

Disk drive: random access device 

0x0003 

Network 

0x0004 

Serial device 

0x0005 

Memory parameter 
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DosError 

♦ Purpose 

Enables or disables system hard-error processing. In the latter case (dis¬ 
able), the process becomes responsible for handling hard errors or excep¬ 
tions returned by API functions. Cannot prevent process termination in 
case of exceptions. 

* Prototype 

unsigned int pascal far DosError 
(unsigned int Enable); 

Enable specifies enabling or disabling of processing; it may have one of 
these values: 

Value Meaning 

0x0000 Disables hard-error processing; enables exception processing 
0x0001 Enables hard-error processing; enables exception processing 
0x0002 Disables exception processing 


DosExecPgm 

♦ Purpose 

Spawns a child process. 

* Prototype 

unsigned int pascal far DosExecPgm 
(char far *PtrFailName, 

PtrFailName is a pointer to a buffer to receive a mime in the event of failure, 
unsigned int LengthFailName, 

LengthFailName is the length of the buffer pointed to by PtrFailName. 

unsigned int ExecFlags, 

ExecFIags specifies how to run the child process, with any of these values: 

Value Meaning 

Run synchronously; suspend parem: until child ends 

Run asynchronously and copy PID to PtrResults — > 
eodeTermitiate 


0x0000 

0x0001 
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0x0002 Run asynchronously; copy PID to PtrResiilts — > 

codeTerminate; make termination and result codes available 
through DosCWait 

0x0003 Run under conditions for tracing 

0x0004 Run asynchronously and independently in the background 
0x0005 Undocumented 
char far *PtrArgs, 

PtrArgs is a pointer to argument strings to be placed in the child’s environ¬ 
ment segment. 

char far *PtrEnv, 

PtrEnv is a pointer to environment strings to be placed in the child’s envi¬ 
ronment segment. 

RESULTCODES far *PtrResults, 

PtrResiilts is a pointer to the RESULTCODES structure (described 
below). 

char far *PtrPgmName); 

PtrPgmName is a pointer to the name of the executable file to run, includ¬ 
ing the file extension. 

♦ Structures 

typedef struct _RESULTCODES 

{ 

unsigned int codeTerminate; /* PID of asynchronous child, or */ 

/* termination code of synchronous */ 
/* child, as listed below. */ 

unsigned int codeResult; /* Exit code of synchronous child. */ 

} 

RESULTCODES; 

The termination code, codeTerminate, may assume one of these values: 


Value 

Meaning 

0x0000 

Normal exit 

0x0001 

Hard-error abort 

0x0002 

Trap operation 

0x0003 

Unintercepted DosKillProcess 
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♦ Purpose 

Ends the calling thread or process. 

♦ Prototype 

void pascal far DosExit 
(unsigned int Terminate, 

If Terminate = 0 , terminate current thread only; if Terminate = 1, termi¬ 
nate current process. 

unsigned int ExitCode); 

ExitCode specifies the exit code for the process. 

DosExitCritSec 

♦ Purpose 

Resumes execution of other threads suspended by DosEnterCritSec. 

♦ Prototype 

void pascal far DosExitCritSec(void); 


DosExitList 

❖ Purpose 

Maintains list of functions to be called upon termination of process; also 
called as last statement in each of these functions. 

♦ Prototype 

unsigned int pascal far DosExitList 
(unsigned int FunctionCode, 

FunctionCode specifies one of these actions: 

Value Meaning 

0x0001 Add function to termination list 

0x0002 Remove function from termination list 

0x0003 Finished, go to next function; used by termination function 


DosExit 
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void (far *)PtrFunction(unsigned int)); 

PtrFunction is a pointer to a function to add to or remove from list; func¬ 
tion itself should be declared void far FunctionName(umigm& int); this 
value should be OL when calling DosExitList from a termination function. 


DosFileLocks 


♦ Purpose 

Locks or unlocks a range in an open file. 

♦ Prototype 

unsigned int pascal far DosFileLocks 
(unsigned short FileHandle, 

FileHandle is the handle previously returned by DosOpen. 
long far ‘PtrUnlockRange, 

PtrUnlockRange is a pointer to a structure (described below). To unlock a 
range, use this parameter and set PtrLockRange to OL. 

long far * PtrLockRange); 

PtrLockRange is a pointer to a structure (described below). To lock a 
range, use this parameter and set PtrUnlockRange to OL. 

♦ Structures 

struct 

{ 

long FileOffset; /* Beginning offset within file. */ 

long RangeLength; /* Number of bytes to lock or unlock. */ 

}; 


OosFindClose 


♦ Purpose 

Closes a search directory. 

* Prototype 

unsigned int pascal far DosFindClose 
(unsigned short DirHandle); 

DIrHaHdSe is the handle previously returned by DosFindFirst. 
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OosFindFirst 

♦ Purpose 

Finds first file or set of files in a directory matching the given filespec and 
attributes. 

♦ Prototype 

unsigned int pascal far DosFindFirst 
(char far *PtrFileSpec, 

PtrFiSeSpec is a pointer to a search string; may contain wildcard characters, 
unsigned short far *PtrDir, 

PtrDir is a pointer to a variable containing the directory-search request. If 
the variable holds the value 0x0001, the system default directory will be 
searched, whereas if the value is OxFFFF, the process’s current directory will 
be used, and a new directory-search handle will be assigned to the variable 
that can be passed to DosFindNext. 

unsigned int Attribute, 

Attribute can have any of the following values, which can be combined for 
use as search criteria: 


Value 

Meaning 

0x0000 

Normal files only 

0x0001 

Read-only files 

0x0002 

Hidden files 

0x0004 

System files 

0x0010 

Subdirectories 

0x0020 

Archived files 


FILEFINDBUFfar *Ptr Find Buffer, 

PtrFIiidBuffer is a pointer to a FILEFINBBUF structure holding the 
results of the search. See description below. 

unsigned int BufferLength, 

BufferLeugth is the length in bytes of the FILEFINBBUF structure. 

unsigned int far *PtrSearchCount, 

PtrSearchCount is a pointer to a variable holding the number of matching 
file names to locate, which the function replaces with the number actually 
found. 
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unsigned long Reserved); 
Reserved must be zero. 

♦ Structures 

typedef struct _F1LEFINDBUF 
{ 


FDATE 

fdateCreation; 

FTIME 

ftimeCreation; 

FDATE 

fdateLastAccess; 

FTIME 

ftimeLastAccess; 

FDATE 

fdateLastWrite; 

FTIME 

ftimeLastWrite; 

unsigned long 

cbFile; 

unsigned long 

cbFileAlloc; 

unsigned int 

attrFile; 

unsigned char 

cchName; 

char 

} 

FILEFINDBUF; 

achName[13]; 


typedef struct _FTIME 

{ 

unsigned twosecs: 5 
unsigned minutes: 6 
unsigned hours: 5 
} 

FTIME; 

typedef struct _FDATE 

{ 

unsigned day: 5 

unsigned month: 4 
unsigned year: 7 

} 

FDATE; 


/* Date of file creation. */ 

/* Time of file creation. */ 

/* Date of last file access. */ 

/ * Time of last file access. * / 

/* Date of last write to file. */ 

/* Time of last write to file. */ 

/* End of file data. */ 

/* File size allocated. */ 

/* File attribute. */ 

/* Length of file name. */ 

/* File name string. */ 

/* These bit fields are in */ 

/* standard DOS and OS/2 */ 

/* directory format. */ 

/* Two-second intervals (0-29). */ 
/* Minutes (0-59). */ 

/* Hours (0-23). */ 


/* Day of month (1-31). 

*/ 

/* Month (1-12). 

*/ 

/* Year (from 1980). 

*/ 


DosFindNext 


♦ Purpose 

Finds next file or set of files in a directory (following DosFindFirst call) 
matching the given filespec and attributes. 
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♦ Prototype 

unsigned int pascal far DosFindNext 
(unsigned short Dir, 

Dir is the search directory handle previously returned by DosFindFirst. 
FILEFINDBUFfar *PtrFindBuffer, 

PtrFmdBuffer is a pointer to a FILEFINDBUF structure holding the 
results of the search. See description below. 

unsigned int BufferLength, 

BufferLength is the length in bytes of the FILEFINDBUF structure. 

unsigned int far *PtrSearchCount); 

PtrSearchCoimt is a pointer to a variable holding the number 01 matching 
file names to locate, which the function replaces with the number actually 
found. 


♦ Structures 

typedef struct _FILEFINDBUF 
{ 


FDATE 

fdateCreation; 

FTIME 

ftimeCreation; 

FDATE 

fdateLastAccess; 

FTIME 

ftimeLastAccess; 

FDATE 

fdateLastWrite; 

FTIME 

ftimeLastWrite; 

unsigned long 

cbFile; 

unsigned long 

cbFileAlloc; 

unsigned int 

attrFile; 

unsigned char 

cchName; 

char 

} 

FILEFINDBUF; 

achName[13]; 


typedef struct _FTIME 

{ 

unsigned twosecs: 5; 
unsigned minutes: 6; 
unsigned hours: 5; 
} 

FUME; 


/* Date of file creation. */ 

/* Time of file creation. */ 

/ * Date of last file access. * / 

/ * Time of last file access. * / 

/ * Date of last write to file. * / 

/ * Time of last write to file. * / 

/* End of file data. */ 

/* File size allocated. */ 

/* File attribute. */ 

/* Length of file name. */ 

/* File name string. */ 

/* These bitfields are in */ 

/* standard DOS and OS/2 */ 

/* directory format. */ 

/* Two-second intervals (0-29). *1 
/* Minutes (0-59). */ 

/* Hours (0-23). */ 
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typedef struct _FDATE 
{ 


unsigned day: 

5; 

/* Day of month (1-31). 

*/ 

unsigned month: 

4; 

/* Month (1-12). 

*/ 

unsigned year: 

7; 

/* Year (from 1980). 

*/ 


FDATE; 


DosFlagProcess 

♦ Purpose 

Sends a signal to a process that has prepared to receive it by calling DosSet- 
SigHandler. 

♦ Prototype 

unsigned int pascal far DosFlagProcess 
(unsigned int PIDProcess, 

PIDProcess is the PID of the target process. 

unsigned int Scope, 

If Scope = 0, set external event flag for target process only. If Scope = 1, 
set external event flags for target process and all its child processes. 

unsigned int FlagNum, 

FlagNum is the number of the flag to set, which may have one of these 
values: 


Value 

Meaning 

0x0001 

Flag A 

0x0002 

Flag B 

0x0003 

Flag C 

unsigned int FlagArg); 


FlagArg is the value to send the target process. 


DosFreeModule 

♦ Purpose 

Frees a dynamic-link module, invalidating its handle. 
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♦ Prototype 

unsigned int pascal far DosFreeModule 
(unsigned int ModuleHandle); 

ModuleHandle is the handle previously returned by DosLoadModule. 


DosFreeSeg 

♦ Purpose 

Frees a memory segment. 

❖ Prototype 

unsigned int pascal far DosFreeSeg 
(unsigned short Selector); 

Selector is the selector of the segment to be freed. 


DosGetCollate 

♦ Purpose _ 

Retrieves the collating sequence table for a supplied country code and code- 

page identifier. 

♦ Prototype 

unsigned int pascal far DosGetCollate 
(unsigned int Buffer, 

Buffer is the size in bytes of buffer to receive table. 

COUNTRYCODE far *PtrCountry, 

PtrCountry is a pointer to the COUNTRYCODE structure containing the 
desired country code and code-page identifier. If PtrCountry - > country 
is 0, the current country code is used and its number is placed there. 

char far * PtrBuffer, 

PtrBuffer is a pointer to the buffer to receive the table, 
unsigned int far * PtrTable); 

PtrTable is a pointer to the variable to receive the number of bytes actually 
written. 

♦ Structures 

typedef struct _COUNTRYCODE 

{ 



Programmer’s 
Guide to OS/2 
appB 


unsigned int country; /* Country code to use. */ 

unsigned int codepage; /* Code page to use. */ 

} 

COUNTRYCODE; 


DosOetOp .." .. 

♦ Purpose 

Retrieves current code page for the process as well as all prepared system 
code pages. 

♦ Prototype 

unsigned int pascal far DosGetCp 
(unsigned int Buffer, 

Buffer is the length of the data area, 
unsigned int far *PtrCountry, 

PtrCountry is a pointer to the buffer to receive the code-page list, 
unsigned int far *PtrCountrylnfo); 

PtrCountrylnfo is a pointer to the variable to receive the number of bytes 
actually written. 


DosGefCtrylnfo 

♦ Purpose 

Retrieves country-dependent information for the given country code and 
code page. 

♦ Prototype 

unsigned int pascal far DosGefCtrylnfo 
(unsigned int BufferSize, 

BufferSize is the size in bytes of the COUNTRYINFO structure. 
COUNTRYCODE far *PtrCountry, 

PtrCountry is a pointer to the COUNTRYCODE structure containing the 
desired country code and code-page identifier. If PtrCountry -> country 
is 0, the current country code is used and its number is placed there. 
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COUNTRYINFO far *PtrCountrylnfo, 

PtrCountrylnfo is a pointer to the COUNTRYINFO structure containing 
country-specific information. 

unsigned intfar *Rr); 

Ptr is a pointer to the variable to receive the number of bytes of information 
actually copied to the COUNTRYINFO structure. 

♦ Structures 

typedef struct _COUNTRYCODE 

{ 

unsigned int country; 
unsigned int codepage; 

} 

COUNTRYCODE; 

typedef struct _COUNTRYINFO 

{ 

unsigned int country; /* Country code. *1 

unsigned int codepage; /* Reserved value, must be 0. */ 

unsigned int fsDateFmt; /* Date format, described below. */ 


char szCurrency[5]; /* Currency-indicator string. */ 

char szThousandsSeparator[2]; /* Thousands-separator string. */ 

char szDecimal[2]; /* Decimal-separator string. *1 

char szDateSeparator[2]; /* Date-separator string. */ 

char szTimeSeparator[2]; /* Time-separator string. *1 

unsigned char fsCurrencyFmt; /* Currency format, described below. */ 

unsigned char cDecimalPlace; /* Decimal places in binary. */ 

unsigned char fsTimeFmt; /* Time format: set = 24 hour; */ 

/* cleared = 12 hour + ’a’ or ’p’. */ 

unsigned int abReserved1[2]; /* Reserved value, must be 0. */ 

char szDataSeparator[2]; /* Data-list-separator string. */ 

unsigned int abReserved2[5]; /* Reserved value, must be 0. */ 

} 

COUNTRYINFO; 

The values for the date format, fsDateFmt, are as follows: 


Value Meaning 

0x0000 mm/dd/yy 
0x0001 dd/mm/yy 
0x0002 yy/mm/dd 


/* Country code to use. *1 

I* Code page to use. */ 
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DosGetDafeTime 


DosGelDBCSEv 


The values for the currency format, fsCurrencyFmt, may be combined: 

Value Meaning 

0x0001 Currency sign follows value, otherwise precedes 

0x0002 Space between sign and value, otherwise none 

0x0004 Currency sign replaces decimal sign, causes other currency 
format values to be ignored 


♦ Purpose 

Retrieves current date and time. 

♦ Prototype 

unsigned int pascal far DosGetDateTime 
(DATETIME far *PtrDateTime); 

PtrDateTime is a pointer to the DATETIME structure to receive the cur¬ 
rent date and time, described below. 

♦ Structures 

typedef struct _DATETIME 


unsigned char 

hours; 

/* 

unsigned char 

minutes; 

/* 

unsigned char 

seconds; 

/* 

unsigned char 

hundredths; 

/* 

unsigned char 

day; 

/* 

unsigned char 

month; 

/* 

unsigned int 

year; 

/* 

int 

timezone; 

/* 

unsigned char 
\ 

weekday; 

/* 

i 

DATETIME; 




Range 0-23. 

*/ 

Range 0-59. 

*/ 

Range 0-59. 

*/ 

Of seconds, range 0-99. 

*/ 

Range 1-31. 

*/ 

Range 1-12. 

*/ 

Range [19]80 to [20]79. 

*/ 

Minutes from GMT signed. 

*/ 

From Sunday, range 0-6. 

*/ 


♦ Purpose 

Retrieves the double-byte character-set environmental variable of a given 
country code and code page. 
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♦ Prototype 

unsigned int pascal far DosGetDBCSEv 
(unsigned int Buffer, 

Buffer is the size in bytes of the buffer to receive the vector. 
COUNTRYCODE far *PtrCountry, 

PtrCountry is a pointer to the COUNTRYCODE structure containing the 
desired country code and code-page identifier. If PtrCountry - > country 
is 0, the current country code is used and its number is placed there. 

char far * Buffer); 

Buffer is a pointer to the buffer to receive the vector. 

♦ Structures 

typedef struct _COUNTRYCODE 

{ 

unsigned int country; /* Country code to use. */ 

unsigned int codepage; /* Code page to use. */ 

} 

COUNTRYCODE; 


DosGetEnv 

♦ Purpose 

Retrieves the address of the process’s environment. 

♦ Prototype 

unsigned int pascal far DosGetEnv 
(unsigned int far * PtrEnvSelector, 

PtrEnvSelector is a pointer to a variable to receive the environment selector, 
unsigned int far * PtrCommandOffset); 

PtrCommandOffset is a pointer to a variable to receive the offset to the 
beginning of the command line. 


DosOetHugeShifl: 

♦ Purpose 

Retrieves the shift count for successive selectors to a huge memory block, 
that is, the number of places to shift the number 1 left to obtain the incre¬ 
ment from one selector to the next. 
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♦ Prototype 

unsigned int pascal far DosGetHugeShift 
(unsigned int far *PtrShiftCount); 

PtrSMftCoimt is a pointer to a variable to receive the shift count. 


DosSetlnfoSeg 


♦ Purpose 

Retrieves selectors to the global and local information segments. 

* Prototype 

unsigned int pascal far DosGetlnfoSeg 
(unsigned short far *PtrGlobalSegSelector, 

PtrGlobalSegSelector is a pointer to a variable to receive the selector for 
the global information segment, which is organized as the structure 
described below. 


unsigned short far *Ptrl_ocalSegSelector); 

PtrLocalSegSelector is a pointer to a variable to receive the selector for the 
local information segment, which is organized as the structure described 
below. 


♦ Structures 

typedef struct _GINFOSEG 

{ 


unsigned long 

time; 

/* 

unsigned long 

msecs; 

/* 

unsigned char 

hour; 

/* 

unsigned char 

minutes; 

/* 

unsigned char 

seconds; 

/* 

unsigned char 

hundredths; 

/* 

unsigned int 

timezone; 

/* 

unsigned int 

cusecTimerlnterval; 

unsigned char 

day; 

/* 

unsigned char 

month; 

/* 

unsigned int 

year; 

/* 

unsigned char 

weekday; 

/* 

unsigned char 

uchMajorVersion; 


unsigned char 

uchMinorVersion; 


unsigned char 

chRevisionLetter; 


unsigned char 

sgCurrent; 

/* 

unsigned char 

sgMax; 

/* 

unsigned char 

cHugeShift; 

/* 


Seconds since 1 /1 /I970. */ 

System time in milliseconds. */ 

Current hour, range 0-23. */ 

Current minute, range 0-59. */ 

Current second, range 0-59. */ 

Hundredths of seconds, range 0-99. */ 

Minutes from GMT -1 = undefined. */ 

/* Interval in milliseconds. */ 

Current day of month, range 1 -31. */ 

Current month, range 1-12. */ 

Current year, [19]80-[20]79. */ 

From Sunday, 0-6. */ 

/* Major version number. */ 

/* Minor version number. */ 

/* Revision letter. */ 

Current foreground screen group. */ 

Maximum number of screen groups. */ 

Shift count for huge segments. */ 
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unsigned char 
unsigned int 
unsigned char 
unsigned char 
unsigned int 
unsigned int 
unsigned int 
unsigned char 


} 

GINFOSEG; 


fProtectModeOnly; 
pidForeground; /* 
fDynamicSched; /* 
csecMaxWait; /* 
cmsecMinSlice; /* 
cmsecMaxSIice; /* 
bootdrive; /* 

amecRAS[32]; /* 
/* 
/* 


/* Protected-mode-only indicator. 
Current foreground process PID. 
Dynamic variation flag (1 = enabled). 
Maximum wait in seconds. 

Minimum time slice in milliseconds. 
Maximum time slice in milliseconds. 
Boot drive. 

Bitmap for system-trace major 
codes. Begins from most significant 
bit of lowest byte. Set = enabled. 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


typedef struct _LINFOSEG 
{ 


unsigned int 

pidCurrent; 

/* PID of current process. 

*/ 

unsigned int 

pidParent; 

/* PID of parent process. 

*/ 

unsigned int 

prtyCurrent; 

/* Priority of current thread. 

*/ 

unsigned int 

tidCurrent; 

/* TID of current thread. 

*/ 

unsigned int 

sgCurrent; 

/* Current screen group. 

*/ 

unsigned int 

sgSub; 

/* Subscreen group. 

*/ 

unsigned short 
} 

LINFOSEG; 

fForeground; 

/* Specifies process in foreground. 

*/ 


DosGetMachineMode 

♦ Purpose 

Shows whether system is currently in real or protected mode. 

❖ Prototype 

unsigned int pascal far DosGetMachineMode 
(unsigned char far *PtrMachineMode); 

PtrMacMneMode is a pointer to a variable to receive the mode: 0 if real, 1 
if protected. 


DosGetIMIessage 

* Purpose 

Retrieves a message from a system message file, optionally replacing sym¬ 
bols in the form %x (where x is a digit from 1 to 9) with corresponding 
strings from a table. 
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$ Prototype 

unsigned int pascal far DosGetMessage 
(char far * far *PtrVTable, 

PtrVTable is the address of a pointer to the table of substitution strings, 
maximum 9. 

unsigned int VCount, 

VCount is the number of strings in table of substitution strings, 0 = ignore 
PtrVTable parameter. 

char far *PtrBuffer, 

PtrBufffer is a pointer to a buffer to receive the message, 
unsigned int BufferLength, 

BufferLeugth is the length in bytes of a buffer to receive the message, 
unsigned int MsgNumber, 

MsgNumber is the message number for the requested message, 
char far *PtrFilel\lame, 

PtrFileName is a pointer to a string giving the path and file name to the 
message file. 

unsigned int far *PtrMsgLength); 

PtrMsgLeugtti is a pointer to a variable to receive the number of bytes 
actually written to the message buffer. 


DosGetModHandie 


* Purpose 

Retrieves the handle to a dynamic-link module, normally to ensure that the 
module has been loaded. 

❖ Prototype 

unsigned int pascal far DosGetModHandie 
(char far *PtrModuleName, 

PfrModuleName is the full file name of the module, 
unsigned int far *PtrModuleHandle); 

PtrModuleBandle is a pointer to a variable to receive the handle. 
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DosGelModName 

* Purpose 

Retrieves the drive, path, and file name of the module corresponding to the 
given handle. 

♦ Prototype 

unsigned int pascal far DosGetModName 
(unsigned int ModuleHandle, 

ModuleHaedle is the handle previously returned by DosLoadModule. 
unsigned int BufferLength, 

BufferLength is the length in bytes of the buffer to receive the file name, 
char far *PtrBuffer); 

PtrBuffer is a pointer to the buffer to receive the file name. 


DosGefPid 


♦ Purpose 

Retrieves identifiers for the current process, its parent, and the calling 
thread. 

♦ Prototype 

unsigned int pascal far DosGetPid 
(PIDINFO far *PtrPIDInfo); 

PtrPIBInf© is a pointer to the structure to receive identifiers. 

♦ Structures 

typedef struct _PIDINFO 

{ 


unsigned int 

pid; 

/* PID of calling process. 

*/ 

unsigned int 

tid; 

/* TID of calling thread. 

*/ 

unsigned int 

pidParent; 

/* PID of parent process. 

*/ 


} 

PIDINFO; 


DosGetProcAddr 


* Purpose 

Finds the address of a procedure within a dynamic-link module. 
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♦ Prototype 

unsigned int pascal far DosGetProcAddr 
(unsigned int ModuleHandle, 

ModiileHandle is the handle previously returned by DosLoadModule. 
char far *PtrProcName, 

PtrProcName is a pointer to the name of the procedure to find. If the string 
begins with #, the remainder is treated as an ordinal value. 

PPFN PtrProcAddress); 

Where PPFN is declared in the definitions header file as follows: typedef 
int (pascal far * far *PPFN)(); (that is, you pass the address of a pointer 
to a pascal far function, which pointer should be declared void (pascal far 
*ptrfn) (args)). The actual pointer to the function receives the address 
within the module. 


DosGetPrty 

♦ Purpose 

Obtains the priority of a thread in the current process or of thread 1 in a 
given process. 

♦ Prototype 

unsigned int pascal far DosGetPrty 


(unsigned int Scope, 

Scope is the scope of the call, with these values: 

Value 

Meaning 

0x0000 

Get priority of thread 1 of process whose PID is specified by 
third parameter 

0x0001 

Get priority of thread in current process whose TID is 
specified by third parameter 


unsigned int far *PtrPriority, 

PtrPriority is a pointer to the variable to receive priority, where the high- 
order byte is the priority class and the low-order byte is the priority level. 

unsigned int PID); 

PID is the identifier described under the Scope parameter above. A zero 
value means the current thread or process. 
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DosGetSeg 

* Purpose 

Accesses a shared memory segment. 


♦ Prototype 

unsigned int pascal far DosGetSeg 
(unsigned short Selector); 


Selector is the segment specified by a selector previously obtained from 
DosAllocSeg. 

DosGetShrSeg 

♦ Purpose 

Obtains a selector to a shared memory segment and increments its reference 
count. 


♦ Prototype 

unsigned int pascal far DosGetShrSeg 
(char far *PtrName, 


PtrName is the name of a shared segment, which must have the form 
\\sharemem\Via/ne, where name is unique and in the form of an OS/2 
file name. 


unsigned short far *PtrSelector); 


PtrSeSector is the variable to receive the new selector. 


DosGetVersion 


♦ Purpose 

Obtains operating-system version number. 

♦ Prototype 

unsigned int pascal far DosGetVersion 
(unsigned int far *PtrVersion); 

PtrVersion is a pointer to a variable to receive the version number, where 
the high-order byte is the major version number and the low-order byte 
is the minor version. 
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DosGiveSeg 

♦ Purpose 

Creates a new selector for a shared memory segment, which can be commu¬ 
nicated to another process. 

♦ Prototype 

unsigned int pascal far DosGiveSeg 
(unsigned short Selector, 

Selector is the original selector. 

unsigned int PID, 

PID is the PID of the process to receive access to the shared segment, 
unsigned short far *PtrNewSelector); 

PtrNewSelector is a pointer to a variable to receive the new selector. 


DosHoidSigna! 

♦ Purpose 

Temporarily disables or reenables signals to a process. 

♦ Prototype 

unsigned int pascal far DosHoldSignal 
(unsigned int Disable); 

If Disable = 1, disables signals; if Disable = 0, enables signals. 


DosInsMessage 

♦ Purpose 

Copies a message between buffers, making optional substitutions. 

♦ Prototype 

unsigned int pascal far DosInsMessage 
(char far * far *PtrVTable, 

PtrYTable is a pointer to the table of substitution strings, maximum 9. 
unsigned int VCount, 

VCount is the number of strings in the table of substitution strings, where 
0 = ignore PtrYTable parameter. 
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char far *PtrMessage, 

PfrMessage is a pointer to input message, 
unsigned int MessageLength, 

MessageLengtti is the length in bytes of input message, 
char far *PtrBuffer, 

PtrBuffer is a pointer to the buffer to receive message, 
unsigned int BufferLength, 

BufferLength is the length in bytes of the buffer to receive message, 
unsigned int far *PtrMsgLength); 

PtrMsgLength is a pointer to a variable to receive the number of bytes 
actually written to message buffer. 


DosKiilProoess 

♦ Purpose 

Terminates a process and (optionally) its children. 

♦ Prototype 

unsigned int pascal far DosKillProcess 
(unsigned int Scope, 

If Scope = 0, kill process and all children; if Scop e = 1, kill process only, 
unsigned int PID); 

PID is the ID of the process to be terminated. 


DosLoadModule 

♦ Purpose 

Loads a dynamic-link module at run-time, returning a handle. 

♦ Prototype 

unsigned int pascal far DosLoadModule 
(char far *PtrFailName, 

PtrFailName is a pointer to the buffer; if the function fails, it will copy the 
name of the module that caused the failure to this buffer. 
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unsigned int FailNameLength, 

FailNameLength is the length in bytes of the above buffer, 
char far *PtrModuleName, 

PtrModuIeName is a pointer to the file name of the module to load, 
unsigned int far *PtrModuleHandle); 

PtrModwleHandle is a pointer to a variable to receive the handle. 


OosLockSeg 

♦ Purpose 

Prevents a discardable segment in memory from actually being discarded. 

♦ Prototype 

unsigned int pascal far DosLockSeg 
(unsigned short Selector); 

Selector is the selector of the segment to lock. 


DosMakePipe 

♦ Purpose 

Creates a pipe. 

♦ Prototype 

unsigned int pascal far DosMakePipe 
(unsigned short far *PtrReadHandle, 

PtrReadHaoidle is a pointer to a variable to receive the read handle, 
unsigned short far *PtrWriteHandle, 

PtrWriteHandle is a pointer to a variable to receive the write handle, 
unsigned int PipeSize); 

PipeSize is the size in bytes of a pipe’s buffer. Value 0 means use default size. 
Maximum is 65,504. 


DosMemAvail 

♦ Purpose 

Finds size of largest block of free memory currently available, a volatile 
quantity. 
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* Prototype 

unsigned int pascal far DosMemAvail 
(unsigned long far *PtrBlockSize); 

PtrBlockSize is a pointer to a variable to receive the size in bytes. 


DosMkdir 


* Purpose 

Creates a directory. 

♦ Prototype 

unsigned int pascal far DosMkdir 
(char far *PtrDirName, 

PtrBirName is a pointer to a valid directory name. 

unsigned long Reserved); 

Reserved must be zero. 


DosMonClose 


♦ Purpose 

Closes a monitor, flushing monitor buffers. 

Prototype 

unsigned int pascal far DosMonClose 
(unsigned short MonitorHandle); 

MonitorHandle is the handle previously returned by DosMonOpen. 


DosMonOpen 

❖ Purpose 

Opens a monitor and obtains a handle for it. 

♦ Prototype 

unsigned int pascal far DosMonOpen 
(char far *DeviceName, 

OeviceName is the name of the device to be monitored, 
unsigned short far *PtrMonitorHandle); 

PtrMoiiitorHaiidle is a pointer to a variable to receive the handle. 
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DosMonRead 


♦ Purpose 

Reads data packets from a monitored device. 

♦ Prototype 

unsigned int pascal far DosMonRead 
(unsigned char far * PtrlnBuffer, 

PtrlnBuffer is a pointer to the monitor input buffer, previously registered 
through DosMonReg. 

unsigned int NoWait, 

If NoWait is 0, wait for data; if NoWait is 1, return immediately, 
unsigned char far *PtrDataBuffer, 

PtrOataBuffer is a pointer to the buffer to receive the data, consisting of 
one of the structures described below. 

unsigned int far *PtrDataBufSize); 

PtrDataBofSize is a pointer to the variable containing the size of the buffer 
to receive the data. 

♦ Structures 

For a keyboard monitor: 

struct 

{ 

unsigned MonFlags; /* Monitor flags, as shown below. */ 

KBDKEYINFO Data; /* Structure; see under KbdCharln. */ 

unsigned DevFlags; /* Device driver flags, as described below. */ 

}; 

For a mouse monitor: 

struct 

{ 

unsigned MonFlags; /* Monitor flags, as shown below. */ 

MOUEVENTINFO Data; /* Structure; see MouReadEventQue. */ 

}; 

For a printer monitor: 

struct 

{ 

unsigned MonFlags; /* Monitor flags, as shown below. */ 
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unsigned PID; /* ID of calling process. */ 

unsigned char Data[n]; /* Data byte(s'l. */ 

}; 

Values for MoiiFIags: 

Bits Meaning 

0-7 For keyboard monitor, original hardware scan code 
For mouse monitor, unused 
For printer monitor, unused 

8 Open packet, should be preserved 

9 Close packet, should be preserved 

10 Flush request, should be preserved 

11-15 Reserved 

Values for DevFlags: 

Bits Meaning 

0-5 Special action code: zero for normal character; 

see Chapter 11 

6 Set if generated by the release of a key 

7 Set if second byte of a 2-byte scan code 

8 Set if typamatic release of a shift key 

9 Set if second byte of an accented 2-byte character 

10-13 Reserved, must be zero 

14-15 Available for sending messages between monitors 


DosMonReg 

♦ Purpose 

Registers a monitor, putting it in the monitor chain for a device and setting 
up monitor buffers. 

♦ Prototype 

unsigned int pascal far DosMonReg 
(unsigned short MonitorHandle, 

MoiiitorHandle is the handle previously returned by OosMonOpen. 
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unsigned char far *PtrlnBuffer, 

PtrlnBuffer is a pointer to the input buffer, whose first word must be its 
size in bytes. 

unsigned char far * PtrOutBuffer, 

PtrOutBiiffer is a pointer to the output buffer, whose first word must be its 
size in bytes. 

unsigned int Position, 

Position is the position requested for the monitor in the chain, with one of 
these values: 

Valoe Meaning 

0x0000 Place anywhere 

0x0001 Place at beginning of chain 

0x0002 Place at end of chain 

unsigned int Index); 

Index is a device-specific index; in the case of a keyboard monitor, for 
example, it is the screen group to be monitored. 


DosMonWrite 


♦ Purpose 

Writes data packets to a device’s output stream. 

♦ Prototype 

unsigned int pascal far DosMonWrite 
(unsigned char far *PtrOutBuffer, 

PtrOutBiiffer is a pointer to the output buffer registered by a previous call 
through DosMonReg. 

unsigned char far *PtrDataBuffer, 

PtrDataBuffer is a pointer to the buffer from which the data is taken, con¬ 
sisting of one of the structures described below. 

unsigned int DataBufSize); 

BataBufSize is the size of the buffer from which the data is taken 
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* Structures 

For a keyboard monitor: 

struct 

{ 

unsigned MonFlags; /* Monitor flags, as described below. */ 

KBDKEYINFO Data; /* Structure; see KbdCharln. */ 

unsigned DevFlags; /* Device driver flags, as described below. */ 

}; 

For a mouse monitor: 

struct 

{ 

unsigned MonFlags; /* Monitor flags, as described below. */ 

MOUEVENTINFO Data; /* Structure; see MouReadEventQue. */ 

}; 

For a printer monitor: 

struct 

{ 

unsigned MonFlags; 
unsigned PID; 
unsigned char Data[n] 

}; 

Values for MonFlags: 

Bits Meaning 

0-7 For keyboard monitor, original hardware scan code 
For mouse monitor, unused 
For printer monitor, unused 
In all cases, set to zero when inserting packet 

8 Open packet, should be preserved 

9 Close packet, should be preserved 

10 Flush request, should be preserved 

11-15 Reserved 

Values for DevFlags: 

Bits Meaning 

0-5 Special action code: zero for normal character; 

see Chapter 11 


/* Monitor flags, as described below. */ 

/* ID of calling process. */ 

/* Data byte(s). */ 
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6 Set if generated by the release of a key 

7 Set if second byte of a 2-byte scan code 

8 Set if typamatic release of a shift key 

9 Set if second byte of an accented 2-byte character 
10-13 Reserved, must be zero 

14-15 Available for sending messages between monitors 


DosfVSove 

♦ Purpose 

Renames a file or assigns it to a different directory. 

♦ Prototype 

unsigned int pascal far DosMove 
(char far *PtrOldName, 

PtrOIdName is a pointer to the old file name, 
char far *PtrNewName, 

PtrNewName is a pointer to the new directory or file name. 

unsigned long Reserved); 

Reserved must be zero. 


DosMuxSemWait 


♦ Purpose 

Waits for the first of a list of semaphores to clear. 

♦ Prototype 

unsigned int pascal far DosMuxSemWait 
(unsigned int far *PtrSemlndex, 

PtrSemlndex is a pointer to a variable that receives the index of the most 
recent semaphore to clear, in the event that any are already clear. 

void far *PtrSemList, 

PtrSemList is a pointer to the structure MUXSEMLIST described below, 
declared void so that it can point to a structure of variable length, as shown. 
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long TimeOut); 

TimeOut is the time in milliseconds the function will wait for a semaphore 
to clear before returning with an error message. With a value of OxFFFFF- 
FFF for TimeOut, the function will wait indefinitely. With a value of 
0x00000000, the function will return immediately. 


♦ Structures 

typedef struct _MUXSEM 

{ 

unsigned int zero; /* Reserved, must be zero. */ 

void far* hsem; /* Handle previously returned by */ 

} /* DosCreateSem or DosOpenSem. */ 

MUXSEM; 

typedef struct _MUXSEMLIST 

{ 

unsigned int cmxs; /* Number of semaphores in list. */ 

MUXSEM amxs[16]; /* Array of MUXSEM structures, *1 


} /* the maximum number of semaphores. */ 

MUXSEMLIST; 

A macro to define a variable-length MUXSEMLIST structure: 

#define DEFINEMUXSEMLIST(name, size) \ 


struct \ 

{ \ 

unsigned int cmxs; \ 

MUXSEM amxs[size]; \ 

} \ 

name; 


DosNewSize 

* Purpose 

Truncates or extends a file. In the latter case, the added data are undefined. 

❖ Prototype 

unsigned int pascal far DosNewSize 
(unsigned short FileHandle, 

FileHandle is the handle previously returned by DosOpen. 

unsigned long NewSize); 

NewSize is the new size in bytes. 
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OosOpen 

♦ Purpose 

Opens or creates a file; opens a device. 

♦ Prototype 

unsigned int pascal far DosOpen 
(char far *PtrFileName, 

PtrFileName is a pointer to a valid file name or reserved device name; no 
wildcards allowed. 

unsigned short far *PtrFileHandle, 

PtrFileHanctle is a pointer to the variable to receive the file handle, 
unsigned int far *PtrAction, 

Ptr Action is a pointer to the report of action taken, with these values: 

Value Meaning 

0x0001 File already existed 

0x0002 File was created 

0x0003 File existed and was truncated 

unsigned long FileSize, 

FileSize specifies the file’s new size in bytes, relevant only when file is 
opened for writing. 

unsigned int Attribute, 

Attribute specifies attributes of the newly created file. Accepts a combina¬ 
tion of these values: 


Value 

Meaning 

0x0000 

Normal file 

0x0001 

Read-only 

0x0002 

Hidden 

0x0004 

System 

0x0020 

Archived 
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unsigned int OpenFlags, 

OpenFIags specifies the following actions, which may be combined: 


Value 

Meaning 


0x0000 

Fail if the file exists 

0x0001 

Open the file 

0x0002 

Truncate the file 

0x0010 

Create the file if it does not exist 

unsigned int OpenMode, 


OpenMode specifies the opening modes, which may be combined, except 
that only one value from Access Modes and one value from Share Modes 

may be used: 

Value 

Meaning 

Access 

0x0000 

Read-only 

Modes 

0x0001 

Write-only 


0x0002 

Read-write 

Share 

0x0010 

Deny read-write; current process has exclusive 

Modes 


access 


0x0020 

Deny write (to other processes) 


0x0030 

Deny read (to other processes) 


0x0040 

Deny none (other processes have free access) 

Other 

0x0080 

Inheritance flag; denies child processes inheritance 

Modes 


of the handle 


0x2000 

Fail-on-error flag; causes functions using this 
handle to fail upon I/O errors instead of the 
system critical-error har dier being invoked and 
notifying the user 


0x4000 

Write-through flag; causes data to be written to 
files (rather than perhaps be left stored in a buffer) 
before the writing function returns 
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0x8000 Direct-access-storage-device (DASD) flag, for 
direct access to a disk drive through the 
DosDevIOCtl function, bypassing the file system 

unsigned long Reserved); 

Reserved must be zero. 


DosOpenQueue 

* Purpose 

Opens a queue. 

❖ Prototype 

unsigned int pascal far DosOpenQueue 
(unsigned int far *PtrOwnerPID, 

PtrOwiserPIB is a pointer to a variable to receive the PID of queue owner, 
unsigned short far *PtrQueueHandle, 

PtrQueiieHandle is a pointer to a variable to receive the handle to the 
queue. 

char far *PtrQueueName); 

PtrQtieueName is a pointer to a string in the form \\queues\\wam^, 
where name is the name in file name format of a queue previously created 
by DosCreateQueue. 


DosOpenSem 

♦ Purpose 

Opens a system semaphore, returning a unique handle. 

♦ Prototype 

unsigned int pascal far DosOpenSem 
(void far * far *PtrSemHandle, 

PtrSemHandSe is the address of a pointer to a variable to receive the handle, 
char far *PtrSemName); 

PtrSeraName is a pointer to a string in the form \\sem \\mme, where 
name is the name in file name format of a semaphore previously created by 
DosCreateSem. 
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DosPeekQueue 

♦ Purpose 

Obtains an element from a queue without removing it. 

♦ Prototype 

unsigned int pascal far DosPeekQueue 
(unsigned short QueueHandle, 

QueueHandle is the handle previously returned by DosCreateQueue or 
DosOpenQueue. 

unsigned long far * PtrResuIt, 

PtrResuIt is a pointer to an information structure (see below), 
unsigned int far *PtrDatal_ength, 

PtrDataLeogth is a pointer to the number of bytes actually copied, 
unsigned long far *PtrDataAddr, 

PtrDataAddr is a pointer to a buffer to receive the element retrieved from 
the queue. 

unsigned int far *PtrElementCode, 

PtrElementCode is the ordinal position of the element in the queue: a value 
of 0x0000 designates the beginning of a queue; the value of the retrieved ele¬ 
ment is copied to this variable before function returns. 

unsigned int NoWait, 

If NoWait is 0, wait for element to be placed in the queue; if NoWait is 1, 
return immediately. 

unsigned char far *PtrElemPrty, 

PtrElemPrty is a pointer to a variable to receive the priority originally 
assigned to an element, in an ascending series of priorities from 0 to 15. 

void far *SemHandle); 

SemHandle is the handle previously returned by DosCreateSem or DosOpen- 
Sem. Variable type is compatible with that for pointers to RAM semaphores. 

♦ Structures 

Structure pointed to by PtrResuIt: 


struct 
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unsigned int pidProcess; 
unsigned int usEventCode; 
}; 


/* PID of originating process. 

/* Event code variable 
/* available for use by processes. 


*/ 

*/ 

*/ 


DosPhysicalDisk 

♦ Purpose 

Obtains information about hard disks. 

♦ Prototype 

unsigned int pascal far DosPhysicalDisk 
(unsigned int Function, 

Function is the type of information to retrieve, which can be one of these 
values: 

Value Meaosog 

0x0001 Number of partitionable disks 
0x0002 Handle for use with Category 9 lOCtl functions 
0x0003 Handle for a disk 
unsigned char far *PtrOutBuffer, 

PtrOutBuffer is a pointer to a buffer to receive output information, 
according to the value for Function: 

Function OutBuffer Information 

1 2 Number of hard disks (0 = none) 

2 2 Handle for use with lOCtl functions 

3 0 None; pointer must be zero 

unsigned int OutBufferLength, 

OutBufferLength is the length of the output buffer specified with PtrOut¬ 
Buffer. 

unsigned char far *PtrParmBuffer, 

PtrParmBuffer is a pointer to a buffer containing input data, according to 
the value for Function: 

Function ParmBuffer Input Parameters 


l 


o 


None. Must be zero. 
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2 String Length String specifying disk, in the form 

disknumher :, starting from 1 

3 2 Handle retrieved by function 2 

unsigned int ParmBufferLength); 

ParmBufferLengtti is the length in bytes of the parameter buffer. 


DosPortAccess 

♦ Purpose 

Requests or releases input/output access to a port or ports, as well as rights 
to set and clear interrupts. 

♦ Prototype 

unsigned int pascal far DosPortAccess 
(unsigned int Reserved, 

Reserved must be zero. 

unsigned int Function, 

If Function - 0, request port access; if Function = 1, release it. 
unsigned int FirstPort, 

FirstPort is the lowest port number in the range, 
unsigned int LastPort); 

LastPort is the highest port number in the range. If same as FirstPort, 
request is for a single port. 


DosPTraee 

♦ Purpose 

Provides access to debugging facilities, allowing parent process to control 
child’s execution and access its code and data. 

♦ Prototype 

This function must be declared explicitly: 

unsigned int pascal far DosPTraee 
(void far *PtrPTraceBuf); 

PtrPTraceBuf is a pointer to a structure of the form shown below. 
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♦ Structures 

struct PtraceBuf 


unsigned int 

pid; 

/* PID of debuggee. 

*/ 

unsigned int 

tid; 

/* TID of debuggee. 

*/ 

unsigned int 

cmd; 

/* Command, then Result, as listed below. 

*/ 

unsigned int 

value; 

/* Value, as listed below. 

*1 

unsigned int 

offv; 

/* Offset. 

*/ 

unsigned int 

segv; 

/* Segment selector. 

*/ 

unsigned int 

mte; 

/* Handle of module containing segment. 

*/ 

unsigned int 

rAX; 

/* AX register. 

*/ 

unsigned int 

rBX; 

/* BX register. 

*/ 

unsigned int 

rCX; 

/* CX register. 

*/ 

unsigned int 

rDX; 

/* DX register. 

*/ 

unsigned int 

rSI; 

/* SI register. 

*/ 

unsigned int 

rBP; 

/* BP register. 

*1 

unsigned int 

rDS; 

/* DS register. 

*/ 

unsigned int 

rES; 

/* ES register. 

*! 

unsigned int 

rIP; 

/* IP register. 

*/ 

unsigned int 

rCS; 

/* CS register. 

*/ 

unsigned int 

rF; 

/* FLAGS register. 

*/ 

unsigned int 

rSP; 

/* SP register. 

*/ 

unsigned int 

rSS; 

/* SS register. 

*1 


Entry values for cmd field: 


Value 

Meaning 

0x0001 

Read memory I-space 

0x0002 

Read memory D-Space 

0x0003 

Read registers 

0x0004 

Write memory I-space 

0x0005 

Write memory D-space 

0x0006 

Write registers 

0x0007 

Go (with signal) 

0x0008 

Terminate child process 

0x0009 

Single step 

OxOOOA 

Stop child process 
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OxOOOB 

Freeze child process 

OxOOOC 

Resume child process 

OxOOOD 

Convert segment number to selector 

OxOOOE 

Get floating-point registers. The segv and offv fields must 
specify the address of a 94-byte buffer containing the 
floating-point register values. 

OxQOOF 

Set floating-point registers, with same proviso as for OxOOOE 

0x0010 

Get library-module name, with value field containing the 
module handle, and segv and offv fields containing the 
address of the buffer to receive the name 

Return values 

for cmd field: 

Value 

Meaning 

0x0000 

Success 

OxFFFF 

Error in value field 

OxFFFE 

About to receive signal 

OxFFFD 

Single-step interrupt 

OxFFFC 

Hit breakpoint 

OxFFFB 

Parity error 

OxFFFA 

Process dying 

0xFFF9 

General-protection fault, type in value field, address of 
responsible code in segv and offv fields 

Return values 

for value field: 

Value 

Meaning 

0x0001 

Bad command 

0x0002 

Child process not found 

0x0005 

Child process untraceable 


DosPurgeQueue 

♦ Purpose 

Purges a queue of all elements, for use by owner of queue. 




444 


Programmer’s 
Guide to OS/2 
appB 


♦ Prototype 

unsigned int pascal far DosPurgeQueue 
(unsigned short QueueHandle); 

QueueHandle is the handle previously returned by DosCreateQueue. 


DosPut^lessage 

♦ Purpose 

Writes a message to a message file. 

♦ Prototype 

unsigned int pascal far DosPutMessage 
(unsigned short FileHandle, 

FileHandle is the handle previously returned by DosOpen, or a standard 
file handle. 

unsigned int MessageLength, 

MessageLengili is the length in bytes of the message. 

char far *PtrMessage); 

PtrMessage is a pointer to the message. 


DosQGurDir 

♦ Purpose 

Obtains path of current directory. 

♦ Prototype 

unsigned int pascal far DosQCurDir 
(unsigned int DriveNumber, 

Values for DriveNumber: 0 = default, 1 = drive A, and so on. 
unsigned char far *PtrPath, 

PtrPath is a pointer to a buffer to receive the path, 
unsigned int far *PtrPathLength); 

PtrPathLength is a pointer to a variable to receive the length of the path. 
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DosQCurDisk 

♦ Purpose 

Obtains current drive number and map of logical drives in system. 

♦ Prototype 

unsigned int pascal far DosQCurDisk 
(unsigned int far *PtrDriveN umber, 

Values for PtrDriveNumber: 1 = drive A, 2 = drive B, and so on. 
unsigned long far *PtrLogicalDrives); 

PtrLogicalMap is a 32-bit map in which the low-order 26 bits represent 
drives; for example, if bit 0 is set, drive A exists; if bit 1 is set, drive B exists. 


DosQFHandState 

* Purpose 

Obtains current state of file handle. 

♦ Prototype 

unsigned int pascal far DosQFHandState 
(unsigned short FileHandle, 

FileHandle is a handle previously returned by DosOpen. 
unsigned int far * PtrStateFlags); 

PtrStateFlags is a pointer to a variable to receive the state. The following 
table shows the possible values, which may be combined, except that only 
one value from Access Modes and one value from Share Modes will be 
used: 



Value 

Meaning 

Access 

0x0000 

Read-only 

Modes 

0x0001 

Write-only 


0x0002 

Read-write 

Share 

0x0010 

Deny read-write; current process has exclusive 

Modes 


access 


0x0020 

Deny write (to other processes) 


0x0030 

Deny read (to other processes) 


0x0040 

Deny none (other processes have free access) 
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DosQFilelnfo 


Other 0x0080 Inheritance flag; denies child processes inheritance 
Modes of the handle 


0x2000 Fail-on-error flag; causes functions using this 
handle to fail upon I/O errors instead of the 
system critical-error handler being invoked and 
notifying the user 

0x4000 Write-through flag; causes data to be written to 
files (rather than perhaps being left stored in a 
buffer) before the writing function returns 

0x8000 Direct-access-storage-device (DASD) flag, for 
direct access to a disk drive through the 
DosDevIOCtl function, bypassing the file system 


♦ Purpose 

Retrieves information about a file. 

♦ Prototype 

unsigned int pascal far DosQFilelnfo 
(unsigned short FileHandle, 

FileHandle is a handle previously returned by DosOpen. 

unsigned int InfoLevel, 

InfoLevel must be 0x0001. 

FILESTATUS far *PtrFileStatus, 

PtrFileStatus is a pointer to a structure to receive information, described 
below. 

unsigned int InfoBufferLength); 

InfoBufferLength is the length of the FILESTATUS structure. 

♦ Structures 

typedef struct _FILESTATUS 

{ 


FDATE 

fdateCreation; 

/* Date of file creation. 

*/ 

FTIME 

ftimeCreation; 

/* Time of file creation. 

*/ 

FDATE 

fdateLastAccess; 

/* Date of last access. 

*/ 

FTIME 

ftimeLastAccess; 

/* Time of last access. 

*/ 

FDATE 

fdateLastWrite; 

/* Date of last write. 

*/ 
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FTIME 

unsigned long 
unsigned long 
unsigned int 
} 

FILESTATUS; 


ftimeLastWrite; 

cbFile; 

cbFileAlloc; 

attrFile; 


/* Time of last write. 
/* End of file data. 

/* File size allocated. 
/* File attributes. 


Date and time information is recorded in structures of this form: 


typedef struct _FTIME 

{ 

unsigned twosecs: 5; 
unsigned minutes: 6; 
unsigned hours: 5; 

} 

FTIME; 


/* These bitfields are in 
/* standard DOS and OS/2 
/* directory format. 

/* Two-second intervals (0-29) 
/* Minutes (0-59). 

/* Flours (0-23). 


typedef struct _FDATE 

{ 

unsigned day: 5; 

unsigned month: 4; 
unsigned year: 7: 

} 

FDATE; 


/* Day of month (1-31). 
/* Month (1-12). 

/* Year (from 1980). 


File attributes are recorded in combinations of these values: 


*/ 

*/ 

*/ 

*/ 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


*/ 

*/ 

*/ 


Value 

Meaning 

0x0000 

Normal files only 

0x0001 

Read-only files 

0x0002 

Hidden files 

0x0004 

System files 

0x0010 

Subdirectories 

0x0020 

Archived files 


DosQFiieModo 

♦ Purpose 

Obtains the attributes of a file. 
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♦ Prototype 

unsigned int pascal far DosQFileMode 
(char far *PtrFileName, 

PtrFileName is a pointer to a file name. 

unsigned int far *PtrAttribute, 

PtrAttribute is a pointer to file attributes, which may be a combination of 
the following values: 


Value 

Meaning 

0x0000 

Normal files only 

0x0001 

Read-only files 

0x0002 

Hidden files 

0x0004 

System files 

0x0010 

Subdirectories 

0x0020 

Archived files 


unsigned long Reserved); 
Reserved must be zero. 


DosQFSInfo 

♦ Purpose 

Obtains information about disk formatting. 

♦ Prototype 

unsigned int pascal far DosQFSInfo 
(unsigned int DriveNumber, 

BriveNiimber is a value from 0 to 26: 0 = current drive, 1 = drive A, and 
so on. 

unsigned int InfoLevel, 

InfoLeve! chooses level of information 1 or 2, as shown below, 
unsigned char far * Ptrlnfo, 

Ptrlnfo is a pointer to one of the structures below, depending on the value 

of InfoLevel. 

unsigned int InfoBufLength); 

InfoBufLength is the length in bytes of a buffer pointed to by Ptrlnfo. 
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DosQHandType 


❖ Structures 

InfoLevel 1 structure: 


typedef struct _FSALLOCATE 
{ 


unsigned long 

idFileSystem; 

/* 

unsigned long 

cSectorUnit; 

/* 

unsigned long 

cUnit; 

/* 

unsigned long 

cUnitAvail; 

/* 

unsigned int 
} 

FSALLOCATE; 

cbSector; 

/* 


File-system identifier. 

Number of sectors per cluster. 
Number of clusters. 

Available clusters. 

Bytes per sector. 


*/ 

*/ 

*/ 

*/ 

*/ 


InfoLevel 2 structure: 
struct 


{ 


FDATE 

fdateCreation; 

FTIME 

ftimeCreation; 

char 

cchName; 

char 

achName[14]; 


typedef struct _FTIME 

{ 

unsigned twosecs: 5; 
unsigned minutes: 6; 
unsigned hours: 5; 

} 

FUME; 

typedef struct _FDATE 
{ 

unsigned day: 5; 

unsigned month: 4; 
unsigned year: 7; 

} 

FDATE; 


/* These data may or may not exist. */ 


/* Volume label creation date. */ 

/* Volume label creation time. */ 

/* Length of volume label. */ 

/* Volume label. */ 

/* These bit fields are in */ 

/* standard DOS and OS/2 */ 

/* directory format. */ 

/* Two-second intervals (0-29). */ 

/* Minutes (0-59) *1 

/* Hours (0-23). */ 


/* Day of month (1-31). */ 

/* Month (1-12). */ 

/* Year (from 1980). */ 


♦ Purpose 

Obtains information as to whether a file handle designates a file or a device. 
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♦ Prototype 

unsigned int pascal far DosQHandType 
(unsigned short FileHandle, 

FileHandle is a handle previously returned by DosOpen. 
unsigned int far *PtrHandType, 

PtrHandType is a pointer to a variable to receive the handle type, which 
may have one of these values: 


Value 

Meaning 

0x0000 

File-system file 

0x0001 

Device 

0x0002 

Pipe 


unsigned int far *PtrDeviceAttr); 

PtrOeviceAttr is a pointer to a variable to receive the device-driver attri¬ 
bute word. 


DosQueryQueue 

♦ Purpose 

Returns current number of elements in a queue, for any process having the 
queue open. 

♦ Prototype 

unsigned int pascal far DosQueryQueue 
(unsigned short QueueHandle, 

QueueHandle is the handle previously returned by DosCreateQueue or 
DosOpenQueue. 

unsigned int far *PtrElemCount); 

PtrElemCount is a pointer to a variable to receive the count of elements. 


DosQVerify 

♦ Purpose 

Obtains system verification mode; that is, whether data written to disk are 
verified. 
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❖ Prototype 

unsigned int pascal far DosQVerify 
(unsigned int far *PtrVerifyOn); 

PtrVerifyOn is a pointer to a value: 1 if verify is on, 0 if verify is off. 


DosRead 

4 Purpose 

Reads from a file or a device. 

❖ Prototype 

unsigned int pascal far DosRead 
(unsigned short FileHandle, 

FileHandle is a handle previously returned by DosOpen. 
void far *PtrBuffer, 

PtrBuffer is a pointer to a buffer to receive data, 
unsigned int BufferLength, 

BufferLength is the number of bytes to be read, 
unsigned int far *PtrBytesRead); 

PtrBytesRead is a pointer to a variable to record the number of bytes actu¬ 
ally read. 


DosReadAsync 

♦ Purpose 

Reads asynchronously from a file or device, that is, returning immediately 
but continuing to read. 

♦ Prototype 

unsigned int pascal far DosReadAsync 
(unsigned short FileHandle, 

FileHandle is a handle previously returned by DosOpen. 
unsigned long far *PtrRAMSem, 

PtrMAMSem is a pointer to a RAM semaphore to be cleared when the 
function has finished copying data. 
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unsigned intfar *PtrErrCode, 

PtrErrorCode is a pointer to a variable to receive a possible error code. 

void far *PtrBuffer, 

PtrBuffer is a pointer to a buffer to receive data, 
unsigned int BufferLength, 

BufferLength is the number of bytes to be read, 
unsigned int far *PtrBytesRead); 

PtrBytesRead is a pointer to a variable to receive the number of bytes actu¬ 
ally read. 


DosReadQueue 


♦ Purpose 

Removes an element from a queue, for the owner of the queue. 

♦ Prototype 

unsigned int pascal far DosReadQueue 
(unsigned short QueueHandle, 

QeeueHandle is a handle previously returned by DosCreateQueue or 
DosOpenQueue. 

unsigned long far *PtrPIDRequest, 

PtrPIORequest is a pointer to an information structure described below. 

unsigned intfar *PtrBufferLength, 

PtrBufferLengtti is a pointer to a variable to receive the number of bytes 
transferred. 

unsigned long far * PtrBuffer, 

PtrBuffer is a pointer to a buffer to receive the element being retrieved, 
unsigned int Element, 

Element is the ordinal position of an element in the queue, where 0x0000 
represents the beginning of the queue or other values are assumed to have 
been returned by DosPeekQueue. 

unsigned int NoWait, 

If NoWait is 0, wait for an element to be placed in queue; if NoWait is 1, 
return immediately. 
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unsigned char far *PtrElemPrty, 

PtrElemPrty is a pointer to a variable to receive priority of element; priori¬ 
ties are in ascending order from 0 to 15. 

void far *SemHandle); 

SemHandle is a handle previously returned by DosCreateSem or Dos- 
OpenSem; if NoWait is 0, function will clear the semaphore on exit. 

♦ Structures 

Structure pointed to by PtrPIBRequest: 
struct 


{ 


unsigned int 

pidProcess; 

/* PID of contributing process. 

*/ 

unsigned int 

usEventCode; 

/* Event code available for 

*/ 

}; 


/* use by applications. 

*/ 


DosReallocHuge 

♦ Purpose 

Reallocates and resizes a huge memory block. 

❖ Prototype 

unsigned int pascal far DosReallocHuge 
(unsigned int NumberSegs, 

NumberSegs is the number of 65,536-byte segments, 
unsigned int PartialSize, 

PartialSize is the number of bytes in the last segment; if 0, no partial seg¬ 
ment is allocated. 

unsigned short Selector); 

Selector is the selector previously returned by DosAllocHuge. 


DosReallocSeg 

❖ Purpose 

Reallocates and resizes a segment. 

♦ Prototype 

unsigned int pascal far DosReallocSeg 
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(unsigned int NewSize, 

NewSize is the new size in bytes; value 0 represents 65,536 bytes, 
unsigned short Selector); 

Selector is the selector previously returned by BosAllocSeg. 


DosResumeThread 


♦ Purpose 

Resumes execution of a thread previously suspended by DosSuspendThread. 

♦ Prototype 

unsigned int pascal far DosResumeThread 
(unsigned int TID); 

TID is the thread identifier previously returned by BosCreateThread. 


DosRmdir 


♦ Purpose 

Removes an empty directory. 

♦ Prototype 

unsigned int pascal far DosRmdir 
(char far *PtrDirName, 

PtrBirName is the name of the directory to be removed. 

unsigned long Reserved); 

Reserved must be zero. 


DosScanErav 


♦ Purpose 

Searches an environment segment for an environment variable. 

♦ Prototype 

unsigned int pascal far DosScanEnv 
(char far *PtrVarName, 

PtrVarName is a pointer to the environment variable name. Does not 
include equal sign. 
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char far * far *PtrPtrResult); 

PtrPtrResult is the address of the pointer that receives the address of the 
variable’s value. 


DosSearchPath 

♦ Purpose 

Searches path (which can be an environment variable or a string argument) 
for a file. Accepts wildcards, in which case the actual file name(s) may have 
to be obtained with DosFindFirst. 

♦ Prototype 

unsigned int pascal far DosSearchPath 


(unsigned int Search, 

Search specifies an action according to the following values, which may be 
combined: 

Value 

Meaning 

0x0001 

Starts search in current directory; if this value is not given, 
the current directory is searched only if expressly named in 
the path 

0x0002 

The PtrPath parameter points to the name of an 
environment variable in the environment of the current 
process; if this value is not given, PtrPath points to a string 
specifying the search path 


char far *PtrPath, 

PtrPath is a pointer to a string as described in the preceding table, 
char far *PtrFileName, 

PtrFileName points to a file name. May contain wildcard characters, 
unsigned char far *PtrBuffer, 

PtrBuffer is a pointer to a buffer to receive the full path name of a file if 
found. 

unsigned int BufferLength); 

BufferLength is the length in bytes of a buffer pointed to by PtrBuffer. 
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DosSelectDisk 

♦ Purpose 

Selects default drive for calling process. 


♦ Prototype 

unsigned int pascal far DosSelectDisk 
(unsigned int DriveNumber); 


DriveNumber is the number of the new drive, beginning with 1 for drive A, 
2 for drive B, and so on. 

DosSelectSession 

♦ Purpose 

Switches child session to foreground. 


♦ Prototype 

unsigned int pascal far DosSelectSession 
(unsigned int SessionID, 


SessionlD is the identifier previously returned by DosStartSession. A value 
of 0x0000 refers to the parent session itself. 


unsigned long Reserved); 


Reserved must be zero. 


DosSemCSear 


* Purpose 

Clears a system semaphore or a RAM semaphore previously set by Dos- 
SemSet or DosSemSetWait. Releases ownership of a semaphore previously 
assigned by DosSemRequest. 

♦ Prototype 

unsigned int pascal far DosSemClear 
(void far *SemHandle); 

SemHaiidle is a handle previously returned by DosCreateSem or Dos- 
OpenSem, or a pointer to a RAM semaphore. 
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DosSemRequest 

♦ Purpose 

Sets a semaphore and returns, after waiting if necessary for the semaphore 
to clear, or returning after a given timeout has elapsed. 


♦ Prototype 

unsigned int pascal far DosSemRequest 
(void far *SemHandle ) 


SemHandle is a handle previously returned by DosCreateSem or Dos- 
OpenSem, or a pointer to a RAM semaphore. 


long TimeOut); 


TimeOut is the time to wait for a semaphore to clear before returning. A 
value of 0 means return immediately, a positive value means wait n millisec¬ 
onds, and a negative value means wait indefinitely. 

DosSemSet 

♦ Purpose 

Sets a semaphore unconditionally. 


♦ Prototype 

unsigned int pascal far DosSemSet 
(void far *SemHandle); 


SemHandle is a handle previously returned by DosCreateSem or Dos- 
OpenSem. 


DosSemSetWait 


♦ Purpose 

Sets a semaphore and waits for it to be cleared, or for a timeout. 

* Prototype 

unsigned int pascal far DosSemSetWait 
(void far * SemHandle, 

SemHandle is a handle previously returned by DosCreateSem or Dos- 
OpenSem. 
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long TimeOut); 

TimeOut is the time to wait for a semaphore to clear before returning. A 
value of 0 means return immediately, a positive value means wait n millisec¬ 
onds, and a negative value means wait indefinitely. 


DosSemWait 


❖ Purpose 

Waits for a semaphore to be cleared, or for a timeout. Returns immediately 
if semaphore is already clear. 

♦ Prototype 

unsigned int pascal far DosSemWait 
(void far *SemHandle ) 

SemHandle is the handle previously returned by DosCreateSem or Dos- 
OpenSem. 

long TimeOut); 

TimeOut is the time to wait for a semaphore to clear before returning. A 
value of 0 means return immediately, a positive value means wait n millisec¬ 
onds, and a negative value means wait indefinitely. 


DosSendSignaS 

♦ Purpose 

Sends a Control-C or Control-Break to the outermost descendant process 
having the corresponding signal handler installed. 

❖ Prototype 

unsigned int pascal far DosSendSignal 
(unsigned int PID, 

PID is the PID of the root process of the desired command subtree, which 
must be a direct child of the calling process, but which may have terminated. 

unsigned int SigNumber); 

SigNtimber is a signal to send: value 0x0001 is Control-C; value 0x0004 is 
Control-Break. 
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DosSetOateTIme 


♦ Purpose 

Sets the code page for the calling process. 

♦ Prototype 

unsigned int pascal far DosSetCp 
(unsigned int CodePage, 

CodePage is the code-page identifier; value 0x0000 is the default system 
page. 

unsigned int Reserved); 

Reserved must be zero. 


* Purpose 

Sets current system date and time. 

❖ Prototype 

unsigned int pascal far DosSetDateTime 
(DATETIME far *PtrDateTime); 

PtrOateTime is a pointer to the DATETIME structure described below. 

♦ Structures 

typedef struct _DATETIME 

{ 


unsigned char 

hours; 

/* Range 0-23. 

*/ 

unsigned char 

minutes; 

/* Range 0-59. 

*/ 

unsigned char 

seconds; 

/* Range 0-59. 

*/ 

unsigned char 

hundredths; 

/* Of seconds; range 0-99. 

*/ 

unsigned char 

day; 

/* Range 1-31. 

*/ 

unsigned char 

month; 

/* Range 1-12. 

*1 

unsigned int 

year; 

/* Range [19]80 to [20]79. 

*/ 

int 

timezone; 

/* Minutes from GMT signed. 

*/ 

unsigned char 
} 

DATETIME; 

weekday; 

/* From Sunday range 0-6. 

*1 
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DosSetFHandState 


♦ Purpose 

Changes the state of the handle flags for a file handle. 

♦ Prototype 

unsigned int pascal far DosSetFHandState 
(unsigned short FileHandle, 

FileHandle is a handle previously returned by DosOpen. 
unsigned int State); 

State is the file-handle state, which may be given one or more of these 

values: 

Value Meaning 

0x0080 Inheritance flag; denies child processes inheritance of the 
handle. 

0x2000 Fail-on-error flag; causes functions using this handle to fail 
upon I/O errors instead of the system critical-error handler 
being invoked and notifying the user 

0x4000 Write-through flag; causes data to be written to files (rather 
than perhaps being left stored in a buffer) before the writing 
function returns 


DosSetFilelnfo 


♦ Purpose 

Sets date and time information for a file. 

♦ Prototype 

unsigned int pascal far DosSetFilelnfo 
(unsigned short FileHandle, 

FileHandle is the handle previously returned by DosOpen. 

unsigned int InfoLevel, 

InfoLeve! must be 0x0001. 

FILESTATUS far *PtrFileStatus, 

PtrFileStatus is a pointer to the FILESTATUS structure described below. 
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unsigned int BufferLength); 


BufferLength is the length of the FILESTATUS structure. 

♦ Structures 

typedef struct _FILESTATUS 


{ 


FDATE 

fdateCreation; 

/* Date of file creation. 

*/ 

FTIME 

ftimeCreation; 

/* Time of file creation. 

*/ 

FDATE 

fdateLastAccess; 

/* Date of last access. 

*/ 

FTIME 

ftimeLastAccess; 

/* Time of last access. 

*1 

FDATE 

fdateLastWrite; 

/* Date of last write. 

*/ 

FTIME 

ftimeLastWrite; 

/* Time of last write. 

*/ 

unsigned long 

cbFile; 

/* Unused by this function. 

*/ 

unsigned long 

cbFileAlloc; 

/* Unused by this function. 

*/ 

unsigned int 
} 

FILESTATUS; 

attrFile; 

/* Unused by this function. 

*/ 


Date and time information is recorded in structures of this form: 


typedef struct _FTIME 

{ 

unsigned twosecs: 5 

unsigned minutes: 6 

unsigned hours: 5 

} 

FTIME; 

typedef struct _FDATE 

{ 

unsigned day: 5; 

unsigned month: 4; 

unsigned year: 7 

} 

FDATE; 


/* These bitfields are in */ 

/* standard DOS and OS/2 */ 

/* directory format. */ 

/* Two-second intervals (0-29). */ 

/* Minutes (0-59). */ 

/* Hours (0-23). */ 


/* Day of month (1-31). */ 

/* Month (1-12). */ 

/* Year (from 1980). */ 


♦ Purpose 

Sets attributes of a file. 
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♦ Prototype 

unsigned int pascal far DosSetFileMode 
(char far *PtrFileName, 

PtrFiSeName is a pointer to a file name. 

unsigned int Attribute, 

Attribute specifies the new attribute; may combine these values (not all 
combinations are allowed): 


Value 

Meaning 

0x0000 

Normal files only 

0x0001 

Read-only files 

0x0002 

Hidden files 

0x0004 

System files 

0x0020 

Archived files 


unsigned long Reserved); 

Reserved must be zero. 


DosSeiFSInfo 


♦ Purpose 

Sets volume label for a disk drive. 

♦ Prototype 

unsigned int pascal far DosSetFSInfo 
(unsigned int DriveNumber, 

DriveNumber is a value from 0 to 26:0 is current drive, 1 is drive A, and so on. 

unsigned int InfoLevel, 
lufoLevel must be 0x0002. 
unsigned char far * Ptrlnfo, 

Ptrlnfo is a pointer to the structure described below, 
unsigned int InfoBufferLength); 


InfoRufferLeugtSi is the length in bytes of the structure pointed to by 
Ptrlnfo. 
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♦ Structures 

struct 

{ 

unsigned int volidjength; /* Length of volume label. */ 

char volid[13]; /* Volume label. */ 

}; 


DosSetMaxFH 

♦ Purpose 

Sets maximum number of file handles for the current process, including 
default system handles and handles used by dynamic-link modules. 

♦ Prototype 

unsigned int pascal far DosSetMaxFH 
(unsigned int Handles); 

Handles is the number of handles: default 20, maximum 255. 


DosSetPrty 

* Purpose 

Sets priority of a process or thread. 

♦ Prototype 

unsigned int pascal far DosSetPrty 
(unsigned int Scope, 

Scope is the scope of the request, which may be given one of these values: 

Value Meaning 

0x0000 Priority for all threads of process 
0x0001 Priority for all threads of process and all descendants 

0x0002 Priority for one thread within current process 

unsigned int PrtyClass, 

PrtyClass is the priority class, which may be given one of these values: 

Value Meaning 
0x0000 Do not change 
0x0001 Idle-time 
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0x0002 Regular 
0x0003 Time-critical 
int Change, 

Change is the change in priority level, from - 31 to +31. 
unsigned int ID); 

ID is the PID or TID, depending on the value of Scope. 


DosSetSession 


♦ Purpose 

Sets status of child session. 

♦ Prototype 

unsigned int pascal far DosSetSession 
(unsigned int SessionID, 

SessionlD is the identifier previously returned by DosStartSession. 

STATUS DATA far *PtrStatusData); 

PtrStatnsData is a pointer to the STATUSDATA structure described 
below. 

♦ Structures 

typedef struct _STATUSDATA 

{ 

unsigned int cb; /* 

unsigned int Selectlnd; /* 

unsigned int Bindlnd; /* 

} /* 

STATUSDATA; 

Values for Selectlnd: 


Value 

Meaning 

0x0000 

Leave as is 

0x0001 

Set as selectable 

0x0002 

Set as nonselectable 


Length in bytes of structure. */ 

Determines if selectable, see below. */ 

Sets future foreground session, see */ 

below. */ 
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Values for Biudlnd: 

Value Meaning 

0x0000 Leave as is 

0x0001 Bind parent and child sessions such that if either is selected, 
child is brought to foreground 

0x0002 Allow sessions to be selected independently 


DosSetSigHandier 

* Purpose 

Installs or removes handler for given signal. 

♦ Prototype 

unsigned int pascal far DosSetSigHandier 
(PFNSIGHANDLER PtrSigHandler, 

PtrSigHandler is a pointer to a function to receive control when the stated 
signal occurs, where PFNSIGHANDLER has this type definition: typedef 
void (far pascal *PFNSIGHANBLER)(rnisigned int, unsigned int);. 

PFNSIGHANDLER far *PtrPrevFn, 

PtrPrevFn is a pointer to a variable to receive the address of the previous 
signal handler; see preceding definition. 

unsigned int far *PtrAction, 

PtrAction is a pointer to a variable to receive the action of the previous sig¬ 
nal handler, with values from 0 to 3. 

unsigned int Action, 

Action specifies the type of request, which may assume one of these values: 

Value Meaning 

0x0000 Install the system default handler 

0x0001 Ignore the signal 

0x0002 Install the specified signal handler for the given signal 

0x0003 Disallow process flag signals from other processes 

0x0004 Reset the specified signal without affecting the disposition of 
the signal 
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unsigned int SigNumber); 

SigNumber may assume one of these values: 

Value Meaning 

0x0001 Control-C 

0x0002 Broken pipe 

0x0003 Kill process 

0x0004 Control-Break 
0x0005 Process flag A 

0x0006 Process flag B 

0x0007 Process flag C 


DosSetVec 

♦ Purpose 

Installs or removes an exception handler. 

♦ Prototype 

unsigned int pascal far DosSetVec 
(unsigned int VecNum, 

VecNum is one of these exception vectors: 


Value 

Meaning 

0x0000 

Division by zero 

0x0004 

Overflow 

0x0005 

Out of bounds 

0x0006 

Invalid opcode 

0x0007 

Processor extension not available 

0x0010 

Processor extension error 

PFN Function, 



Function is a pointer to the exception handler, where PFN has this type def¬ 
inition: typedef int (pascal far *PFN)( );. A NULL value directs the func¬ 
tion to remove the current exception handler. 
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PPFN PrevFunction); 

PrevFunction is the address of the pointer to the previous exception han¬ 
dler, where PPFN has this type definition: typedef let (pascal far * far 
*PPFN)();. The process may chain to this handler. 


DosSefVersfy 

♦ Purpose 

Turns verification of data written to disk on or off. 

♦ Prototype 

unsigned int pascal far DosSetVerify 
(unsigned int Verify); 

If Verify is 0, disable verification; if Verify is 1, enable verification. 

DesSSeep 

♦ Purpose 

Causes thread to block for specified period. 

♦ Prototype 

unsigned int pascal far DosSleep 
(unsigned long Time); 

Time specifies that the process sleeps for approximately the given time, in 
milliseconds. Value of 0 means that process gives up present time slice. 


DosStartSesslon 

♦ Purpose 

Starts another session, specifying program to be run in it. 

♦ Prototype 

unsigned int pascal far DosStartSession 
(STARTDATA far *PtrStartData, 

PtrStartData is a pointer to the STARTDATA structure described below. 

unsigned int far *PtrSessionlD, 

PtrSessionID is a pointer to a variable to receive the identifier of the child 


session. 
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unsigned int far *PtrPID); 

PtrPID is a pointer to a variable to receive the PID of the child process. 

♦ Structures 


typedef struct _STARTDATA 
{ 


unsigned int 

cb; 

/* Length of structure; must be 22. 

*/ 

unsigned int 

Related; 

/* See table below. 

*/ 

unsigned int 

FgBg; 

/* See table below. 

*/ 

unsigned int 

TraceOpt; 

/* See table below. 

*/ 

char far 

* PgmTitle; 

/* Title of program, to 32 bytes; 

*/ 


/* NULL 

. pointer = use PgmName as title. 

*/ 

char far 

*PgmName; 

/* Full path name of program. 

*/ 

unsigned char far 

*Pgmlnputs; 

/* Arguments to pass to program. 

*/ 

unsigned char far 

*TermQ; 

/* Full path name to a queue through 

*/ 



/* which parent may be notified of 

*/ 



/* child session’s termination; 

*/ 

} 


/* optional. 

*/ 


STARTDATA; 

Values for Related field: 

Value Meaning 

0x0000 New session is independent 

0x0001 New session is a child session, subject to control through 
DosSelectSession, DosSetSession, or DosStopSession 

Values for FgRg field: 

Value Meaning 

0x0000 Session is started in foreground 
0x0001 Session is started in background 

Values for TraceOpt field: 

Value Meaning 

0x0000 Execute under conditions for tracing 
0x0001 Do not execute under conditions for tracing 



Summary of the API 


DosStopSession 

♦ Purpose 

Terminates a child session. 

♦ Prototype 

unsigned int pascal far DosStopSession 
(unsigned int Scope, 

Scope is the scope of the function, with these values: 

Value Meaning 

0x0000 Stop the specified session 
0x0001 Stop the session and all descendants 
unsigned int SessionID, 

SessionlD is the session identifier previously returned by DosStartSession. 

unsigned long Reserved); 

Reserved must be zero. 


DosSubAlloc 

♦ Purpose 

Allocates memory within a data segment previously allocated by DosAlloc- 
Seg or DosAllocShrSeg and initialized by DosSubSet. 

* Prototype 

unsigned int pascal far DosSubAlloc 
(unsigned short Selector, 

Selector is the selector to the desired segment, 
unsigned int far *PtrOffset, 

PtrOffset is a pointer to a variable to receive the offset of the allocation, 
unsigned int Size); 

Size is the size of the requested block. 


DosSuhFree 

❖ Purpose 

Frees memory block previously allocated by DosSubAlloc. 
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♦ Prototype 

unsigned int pascal far DosSubFree 
(unsigned short Selector, 

Selector is the selector to the desired segment, 
unsigned int BlockOffset, 

BlockOffset is the offset previously returned by OosSubAlloc. 
unsigned int BlockSize); 

BloekSize is the size in bytes of the block to be freed. 


DosSubSet 


♦ Purpose 

Prepares a segment for suballocation or changes the size of a previously ini¬ 
tialized segment. 

♦ Prototype 

unsigned int pascal far DosSubSet 
(unsigned short Selector, 

Selector is the selector of the intended data segment, 
unsigned int Flags, 

Flags states whether to initialize the segment or to change its size, with these 
possible values: 

Value Meaning 

0x0000 Change segment size (call DosReallocSeg before increasing it) 
0x0001 Initialize the segment 
unsigned int SegmentSize); 

SegmentSize is the new size of the segment in bytes, which is rounded up to the 
next multiple of 4, except that a value of 0 denotes a 64-kilobyte segment. 


DosSuspendThread 

♦ Purpose 

Suspends execution of a thread in the same process. 
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♦ Prototype 

unsigned int pascal far DosSuspendThread 
(unsigned int TID); 

TIB is the thread to be suspended. 


DosSystemServlce 

♦ Purpose 

Requests certain system functions. 

♦ Prototype 

unsigned int pascal far DosSystemService 
(unsigned int Category, 

Category is the type of function requested or event awaited, with these pos¬ 
sible values: 

Value Meaning 

0x0000 Session manager services 
0x0001 Hard-error services 
0x0002 Print-screen services 
void far *PtrRequest, 

PtrRequest is a pointer to a structure containing information about the 
desired function, in either of two formats, as described below. 

void far *PtrResponse); 

PtrResponse is a pointer to a structure containing return information 
about the function, in any of three formats, as described below. 

♦ Structures 

Request-packet structure for Category 0: 

struct 

{ 

unsigned int SMService; /* Type of service, as below. */ 

unsigned int SMSubFunction; /* Freeze or thaw subfunction, as below. */ 

unsigned int Item; /* Target item, as below. */ 

}; 



472 


Programmer’s 
Guide to OS/2 
appB 


Values for SMService: 

Value Meaning 

0x0000 Wait for session-manager hotkey 

0x0001 Perform freeze or thaw subfunction 

Values for SMSubFunction, with SMService value of 1: 


Value 

Meaning 

0x0000 

Freeze process 

0x0001 

Thaw process 

0x0002 

Freeze screen group 

0x0003 

Thaw screen group 

0x0004 

Get real mode process identifier 

Values for Item: 

Value 

Meaning 

0-1 

Process identifier 

2-3 

Screen-group number 


Response-packet structure, for SMService value of 0: 

struct 

{ 

unsigned int HotKeyDevice; /* Type of hotkey device, as below. */ 

unsigned int TimeStamp; /* For mouse, gives time of hotkey */ 

}; /* event. For keyboard, identifies */ 

/* hotkey */ 

Values for HotKeyDevice: 


Value Meaning 

0x0000 Mouse 
0x0001 Keyboard 

Request-packet structure for Category 1 : 


struct 

{ 


/* Response to hard error returned by */ 
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unsigned int HEService; /* previous Category 1 request, with *7 

}; /* values given below. */ 

Values for HEService: 

Value Meaning 

0x0000 Return immediately from function that caused error 
0x0001 Terminate function that generated error 
0x0002 Retry operation that caused error 
0x0003 Ignore error 


Response-packet structure for Category 1: 


struct 

{ 

unsigned int SGNumber; /* Screen group where error occurred. */ 

unsigned int ProcessID; /* PID of process causing error. */ 

unsigned int MsgNumber; /* Number to give DosGetMessage. */ 

unsigned int ValidResponse; /* Valid responses as given below. */ 

unsigned int DefaultResponse; /* Default responses as given below. */ 

unsigned int NumStrings; /* Number of strings in Buffer field. */ 

unsigned int BUFLEN; /* Size in bytes of Buffer field. */ 

char Buffer[BUFLEN]; /* Receives strings to pass to */ 

}; /* DosGetMessage in order and */ 

/* direct succession. */ 


Response-packet structure for Category 2 (there is no request packet): 

struct 

{ 

unsigned int Keystroke; /* Keystroke pressed, as below. */ 

}; 

Values for Keystroke field: 


Value Meaning 

0x0000 Shift-PrtSc 
0x0001 Control-PrtSc 


DosTimerAsync 

♦ Purpose 

Creates and returns a handle to a timer that clears a semaphore after the 
prescribed interval. 
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♦ Prototype 

unsigned int pascal far DosTimerAsync 
(unsigned long Time, 

Time is the time in milliseconds before a semaphore is cleared, 
void far ’SemHandle, 

SemHandle is a system semaphore handle previously returned by Dos- 
CreateSem. 

unsigned short far *PtrTimer); 

PtrTimer is a pointer to a variable to receive the timer handle. 


DosTimerStart 


♦ Purpose 

Creates a timer that clears a semaphore at regular intervals until stopped by 
DosTimerStop. 

* Prototype 

unsigned int pascal far DosTimerStart 
(unsigned long Time, 

Time is the time in milliseconds before the timer is cleared, 
void far ’SemHandle, 

SemHandle is the system semaphore handle previously returned by 
DosCreateSem. 

unsigned short far ’PtrTimer); 

PtrTimer is the pointer to a variable to receive the timer handle. 


DosTimerStop 

♦ Purpose 

Stops a timer. Does not clear related semaphore. 

♦ Prototype 

unsigned int pascal far DosTimerStop 
(unsigned short Timer); 

Timer is the timer handle previously returned by DosTimerAsync or Dos¬ 
TimerStart. 
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DosUnlockSeg 

❖ Purpose 

Unlocks a discardable segment, freeing the system to discard it. 

♦ Prototype 

unsigned int pascal far DosUnlockSeg 
(unsigned short Selector); 

Selector is the selector to a segment to be unlocked. 


DosWrite 

* Purpose 

Writes to the file or device identified by the provided handle. 

♦ Prototype 

unsigned int pascal far DosWrite 
(unsigned short FileHandle, 

FileHandle is a handle previously returned by DosOpen. 
void far * PtrBuffer, 

PtrBuffer is a pointer to a buffer containing the data. 

unsigned int BufferLength, 

BufferLength is the length in bytes of the data buffer, 
unsigned int far *PtrBytesWritten); 

PtrBytesWritten is a pointer to a variable to receive the number of bytes 
actually written. 


DosWriteAsync 

♦ Purpose 

Writes asynchronously to the file or device identified by the provided han¬ 
dle, returning immediately but continuing to write. 

♦ Prototype 

unsigned int pascal far DosWriteAsync 
(unsigned short FileHandle, 

FileHandle is a handle previously returned by DosOpen. 
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unsigned long far *PtrRAMSemaphore, 

PtrRAMSemaphore is a pointer to a RAM semaphore to be cleared when 
the write operation is completed. 

unsigned intfar *PtrErrorCode, 

PtrErrorCode is a pointer to a variable to receive a possible error code, 
void far *PtrBuffer, 

PtrBuffer is a pointer to a buffer containing the data, 
unsigned int BufferLength, 

BufferLength is the length in bytes of the data buffer, 
unsigned intfar *PtrBytesWritten); 

PtrBytesWritten is a pointer to a variable to receive the number of bytes 
actually written. 


DosWriteOueue 

♦ Purpose 

Writes an element to a queue, assigning it a priority. 

♦ Prototype 

unsigned int pascal far DosWriteOueue 
(unsigned short QueueHandle, 

QueueHandle is a handle previously returned by DosCreateQueue or 
BosOpenQueue. 

unsigned int Request, 

Request is an event code available for program use. 
unsigned int BufferLength, 

BufferLength is the number of bytes to be written, 
unsigned char far * PtrBuffer, 

PtrBuffer is a pointer to the buffer containing the element to be written, 
unsigned int Priority); 

Priority is the priority, in ascending order from 0 to 15. 



Summary of the API 


KbdCharln 

♦ Purpose 

Reads a character from a logical keyboard. Does not echo characters. 

♦ Prototype 

unsigned int pascal far KbdCharln 
(KBDKEYINFO far *PtrKbdKeylnfo, 

PtrKbdKeylnfo is a pointer to the KBDKEYINFO structure described 
below. 

unsigned int NoWait, 

If NoWait is 0, wait for character; if NoWait is 1, return immediately, 
unsigned short KbdHandle); 

KbdHandle is a handle previously returned by KbdOpen. 

♦ Structures 

typedef struct _KBDKEYINFO 


unsigned char 
unsigned char 
unsigned char 
unsigned char 
unsigned int 
unsigned long 
} 

KBDKEYINFO; 

chChar; 

chScan; 

fbStatus; 

bNIsShift; 

fsState; 

time; 

/* Translated character, see below. 

/* Scan code. 

/* Keystroke state, described below. 

/* Must be zero. 

/* State of shift keys, described below. 
/* Time stamp in milliseconds. 

Special values for chChar: 


Value 

Meaning 


0x0000 



OxOOEO 

Denotes extended ASCII code 


Values for fbStatus, which may be combined: 

Value Meaning 

0x0001 Shift key received (raw mode, shift report on) 
0x0020 Conversion required 
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0x0040 

Final character received (of double-byte character) 

0x0080 

Interim character received (of double-byte character) 

Values for fsState, which may be combined: 

Value 

Meaning 

0x0000 

Shift keys up 

0x0001 

Right Shift key down 

0x0002 

Left Shift key down 

0x0004 

Either Control key down 

0x0008 

Either Alt key down 

0x0010 

Scroll Lock turned on 

0x0020 

Num Lock turned on 

0x0040 

Caps Lock turned on 

0x0080 

Insert turned on 

0x0100 

Left Control key down 

0x0200 

Left Alt key down 

0x0400 

Right Control key down 

0x0800 

Right Alt key down 

0x1000 

Scroll Lock key down 

0x2000 

Num Lock key down 

0x4000 

Caps LockLey down 

0x8000 

Sys Req key down 


KbdCSose 


♦ Purpose 

Closes a logical keyboard, flushing the buffer and freeing the focus if 
appropriate. 

♦ Prototype 

unsigned int pascal far KbdClose 
(unsigned short KbdHandle); 

KbdHandle is a handle previously returned by KbdOpen. 
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KbdDeRegisteir 

♦ Purpose 

Releases previously registered keyboard subsystems and restores default 
functions for current screen group. 

♦ Prototype 

unsigned int pascal far KbdDeRegister 
(void); 


KbdFlushBuffer 

♦ Purpose 

Flushes logical keyboard buffer. Acts on default keyboard or keyboard with 
the focus. 

♦ Prototype 

unsigned int pascal far KbdFlushBuffer 
(unsigned short KbdHandle); 

KbdHandle is a handle previously returned by KbdOpen. 

KbdFreeFocus 

♦ Purpose 

Frees the focus from a logical keyboard. 

♦ Prototype 

unsigned int pascal far KbdFreeFocus 
(unsigned short KbdHandle); 

KbdHandle is a handle previously returned by KbdOpen. 

KbdGefCp 

♦ Purpose 

Obtains current code-page identifier for a logical keyboard. 

♦ Prototype 

unsigned int pascal far KbdGetCp 
(unsigned long Reserved, 


Reserved must be zero. 
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unsigned intfar *PtrCodePagelD, 

PtrCodePageH) is a pointer to a variable to receive the code-page identifier, 
unsigned short KbdHandle); 

KbdHandle is a handle previously returned by KbdOpen. 


SCbdOetFooys 


♦ Purpose 

Obtains focus for a logical keyboard. A process must have freed the focus 
by calling KbdFreeFocus. 

♦ Prototype 

unsigned int pascal far KbdGetFocus 
(unsigned int NoWait, 

If NoWait is 0, wait for focus; if NoWait is 1, return immediately, 
unsigned short KbdHandle); 

KbdHandle is a handle previously returned by KbdOpen. 


KbdGetStatus 


♦ Purpose 

Obtains status of a logical keyboard. 

♦ Prototype 

unsigned int pascal far KbdGetStatus 
(KBDINFOfar *PtrKbdlnfo, 

PtrKbdlnfo is a pointer to the KBDINFO structure described below, 
unsigned short KbdHandle); 

KbdHandle is a handle previously returned by KbdOpen. 

♦ Structures 

typedef struct _KBDINFO 

{ 

unsigned int cb; /* Length of structure, must be OxOOOA. */ 

unsigned int fsMask; /* Keyboard modes, as described below, */ 

unsigned int chTurnAround; /* Turnaround character. */ 
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unsigned intfslnterim; /* Interim character flags, as below. */ 

unsigned int fsState; / * State of shift keys, as below. */ 

} 

KBDINFO; 

Values for fsMask, which may be combined: 


Value 

Meaning 

0x0000 

No states set 

0x0001 

Echo mode on 

0x0002 

Echo mode off 

0x0004 

Raw mode on 

0x0008 

Cooked mode on 

0x0080 

Two-byte turnaround character 

0x0100 

Shift report on 


Values for fslnterim: 

Value Meaning 

0x0020 Request for character conversion 

0x0080 Interim character flag on 

Values for fsState, which may be combined: 


Value 

Meaning 

0x0000 

Shift keys up 

0x0001 

Right shift key down 

0x0002 

Left shift key down 

0x0004 

Control key down 

0x0008 

Alt key down 

0x0010 

Scroll lock on 

0x0020 

Num Lock on 

0x0040 

Caps Lock on 

0x0080 

Insert on 
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KbdOpen 


KbdPeek 


♦ Purpose 

Opens a logical keyboard, initializing it with system default code page. 

♦ Prototype 

unsigned int pascal far KbdOpen 
(unsigned short far *PtrKbdHandle); 

PtrKbdHandle is a pointer to a variable to receive the handle to a logical 
keyboard. 


* Purpose 

Obtains information on a keystroke, copying it from the keyboard buffer. 
Does not echo characters. 

* Prototype 

unsigned int pascal far KbdPeek 
(KBDKEYINFO far *PtrKbdKeylnfo, 

PtrKbdKeylnfo is a pointer to a KBDKEYINFO structure, described 
below. 

unsigned short KbdHandle); 

KbdHandle is a handle previously returned by KbdOpen. 

* Structures 


typedef struct _KBDKEYINFO 
{ 


unsigned char 

chChar; 

/* Translated character, see below. 

*/ 

unsigned char 

chScan; 

/* Scan code. 

*/ 

unsigned char 

fbStatus; 

/* Keystroke state, described below. 

*/ 

unsigned char 

bNIsShift; 

/* Must be zero. 

*/ 

unsigned int 

fsState; 

/* State of shift keys, described below. 

*/ 

unsigned long 
} 

KBDKEYINFO; 

time; 

/* Time stamp in milliseconds. 

*/ 


Special values for chChar: 


Value Meaning 

0x0000 Denotes extended ASCII code 
OxOOEO Denotes extended ASCII code 
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KbdRegister 


Values for fbStatus, which may be combined: 

Value Meaning 

0x0001 Shift key received (raw mode, shift report on) 

0x0020 Conversion required 

0x0040 Final character received (of double-byte character) 
0x0080 Interim character received (of double-byte character) 

Values for fsState, which may be combined: 


Value 

Meaning 

0x0000 

Shift keys up 

0x0001 

Right Shift key down 

0x0002 

Left Shift key down 

0x0004 

Either Control key down 

0x0008 

Either Alt key down 

0x0010 

Scroll Lock turned on 

0x0020 

Num Lock turned on 

0x0040 

Caps Lock turned on 

0x0080 

Insert turned on 

0x0100 

Left Control key down 

0x0200 

Left Alt key down 

0x0400 

Right Control key down 

0x0800 

Right Alt key down 

0x1000 

Scroll Lock key down 

0x2000 

Num Lock key down 

0x4000 

Caps Lock key down 

0x8000 

Sys Req key down 


❖ Purpose 

Registers a keyboard subsystem for a logical keyboard, replacing one or 
more default functions with functions in a dynamic-link module. 
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♦ Prototype 

unsigned int pascal far KbdRegister 
(char far *PtrModuleName, 

PtrModuleName is a pointer to a module containing replacement key¬ 
board functions. 

char far *PtrEntryName, 

PtrEntryName is a pointer to the name of the entry-point function to 
replace specified default functions, in the form given below. 

unsigned long Functions); 

Functions specifies the functions to be replaced, as any combination of the 
following values: 


Value 

Meaning 

0x00000001 

Replace KbdCharln 

0x00000002 

Replace KbdPeek 

0x00000004 

Replace KbdFlushBuffer 

0x00000008 

Replace KbdGetStatus 

0x00000010 

Replace KbdSetStatus 

0x00000020 

Replace KbdStringln 

0x00000040 

Replace KbdOpen 

0x00000080 

Replace KbdClose 

0x00000100 

Replace KbdGetFocus 

0x00000200 

Replace KbdFreeFocus 

0x00000400 

Replace KbdGetCp 

0x00000800 

Replace KbdSetCp 

0x00001000 

Replace KbdXlate 

0x00002000 

Replace KbdSetCustXt 


♦ Comments 

You must write the entry-point function pointed to by PtrEntryName in 
this form: 

void far FuncName 
(unsigned short DataSegSelector, 

DataSegSelector is a data-segment selector of the process that calls the key¬ 
board function. 
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unsigned int Reservedl, 

Reserved! must not be altered, 
unsigned int Function, 

Function is the function code of the function request, one of the following 
values: 


Value 

Meaning 

0x0000 

KbdCharln called 

0x0001 

KbdPeek called 

0x0002 

KbdFlushBuffer called 

0x0003 

KbdGetStatus called 

0x0004 

KbdSetStatus called 

0x0005 

KbdStringln called 

0x0006 

KbdOpen called 

0x0007 

KbdClose called 

0x0008 

KbdGetFocus called 

0x0009 

KbdFreeFocus called 

OxOOOA 

KbdGetCp called 

OxOOOB 

KbdSetCp called 

OxOOOC 

KbdXlate called 

OxOOOD 

KbdSetCustXt called 

unsigned lone 

\ Reserved2, 


Reserved! must not be altered. 

unsigned int Paraml, 
unsigned int Param2, 
unsigned int Parann3, 
unsigned int Param4, 
unsigned int Param5, 
unsigned int Param6); 

Paraml,..., Param6 specify up to six unsigned values passed with the orig¬ 
inal keyboard function call; the number of parameters is dependent on the 
function. 
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KbdSetCp 

♦ Purpose 

Sets the code page for a logical keyboard. 

♦ Prototype 

unsigned int pascal far KbdSetCp 
(unsigned int Reserved, 

Reserved must be zero. 

unsigned int CodePagelD, 

CodePagelB is the code-page identifier. Value 0 is the default code page, 
unsigned short KbdHandle); 

KbdHandle is the handle previously returned by KbdOpen. 


KbdSetCustXt 


♦ Purpose 

Installs a custom translation table for a logical keyboard. 

* Prototype 

unsigned int pascal far KbdSetCustXt 
(unsigned int far *PtrTransTbl, 

PtrTransTbl is a pointer to a translation table, whose format is discussed in 
Appendix C of the OS/2 Programmer's Reference. 

unsigned short KbdHandle); 

KbdHandle is a handle previously returned by KbdOpen. 


KbdSetStatus 

* Purpose 

Sets the status for a logical keyboard. 

♦ Prototype 

unsigned int pascal far KbdSetStatus 
(KBDINFO far *PtrKbdlnfo, 

PtrKbdlnffo is a pointer to the KBBINFO structure shown below. 
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unsigned short KbdHandle); 

KbdHandle is a handle previously returned by KbdOpen. 

♦ Structures 

typedef struct _KBDINFO 

unsigned int cbj /* Length of structure, must be OxOOOA. 

unsigned int fsMask; /* Keyboard modes, as described below, 

unsigned int chTurnAround; /* Turnaround character, 
unsigned int fslnterim; /* Interim character flags, as below, 

unsigned int fsState; /* State of shift keys, as below. 

} 

KBDINFO; 

Values for fsMask, which may be combined: 


Value 

Moaning 

0x0000 

No states set 

0x0001 

Echo mode on 

0x0002 

Echo mode off 

0x0004 

Raw mode on 

0x0008 

Cooked mode on 

0x0080 

Two-byte turnaround character 

0x0100 

Shift report on 


Values for fslnterim: 


Value 

Meaning 

0x0020 

Request for character conversion 

0x0080 

Interim character flag on 

Values for fsState, which may be combined: 

Value 

Meaning 

0x0000 

Shift keys up 

0x0001 

Right Shift key down 

0x0002 

Left Shift key down 
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0x0004 

Control key down 

0x0008 

Alt key down 

0x0010 

Scroll Lock on 

0x0020 

Num Lock on 

0x0040 

Caps Lock on 

0x0080 

Insert on 


KbdStringln 

♦ Purpose 

Reads a string from a logical keyboard. Echoes characters to the screen if 
echo and cooked modes are on. 

♦ Prototype 

unsigned int pascal far KbdStringln 
(char far *PtrBuffer, 

PtrBuffer is a pointer to a buffer to receive the string. 

STRINGINBUFfar *Ptrl_ength, 

PtrLengtfo is a pointer to the STRINGINBUF structure that receives 
lengths, as described below. 

unsigned int NoWait, 

If NoWait is 0, wait for next turnaround character or buffer is full; if 
NoWait is 1, return immediately with whatever characters are available. 

unsigned short KbdHandle); 

KbdBaodle is the handle previously returned by KbdOpen. 

♦ Structures 

typedef struct _STRINGINBUF 

{ 

unsigned int cb; /* Length of buffer, maximum FF bytes. */ 

unsigned int cchln; /* Number of bytes read, maximum */ 

} /* FF bytes. */ 

STRINGINBUF; 


KbdSynch 

♦ Purpose 

Synchronizes access to the keyboard device driver, for use by a subsystem 
only. 
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KbdXIate 


♦ Prototype 

unsigned int pascal far KbdSynch 
(unsigned int NoWait); 

If NoWait is 0, wait for access to the keyboard router; if NoWait is 1, 
return immediately. 


* Purpose 

Translates a scan code and its shift states into a character value. 

* Prototype 

unsigned int pascal far KbdXIate 
(KBDTRANSLATE far *PtrKeyStroke, 

PtrKeyStroke is a pointer to the KBDTRANSLATE structure, described 
below. 

unsigned short KbdHandle); 

KbdHandle is a handle previously returned by KbdOpen. 

* Structures 

typedef struct _KBDTRANSLATE 


{ 


unsigned char 

chChar; 

/* Character value (is replaced). 

*/ 

unsigned char 

chScan; 

/* Scan code. 

*/ 

unsigned char 

fbStatus; 

/* State of scan code, as below. 

*/ 

unsigned char 

bNIsShift; 

/* Must be zero. 

*/ 

unsigned int 

fsState; 

/* State of shift keys, as below. 

*1 

unsigned long 

time; 

/* Time stamp in milliseconds. 

*1 

unsigned int 

fsDD; 

/* Defined for monitor packets. 

*/ 

unsigned int 

fsXIate; 

/* 0 = incomplete translation; 

*/ 



/* 1 = complete translation. 

*/ 

unsigned int 

fsShift; 

/* Set to 1 for successive calls 

*/ 



/* in translation, else 0. 

*/ 

unsigned int 
} 

KBDTRANSLATE; 

sZero; 

/* Must be zero. 

*/ 


Values for fbStatus, which may be combined: 


Value Meaning 

0x0001 Shift key received (raw mode, shift report on) 
0x0020 Conversion required 



490 


Programmer’s 
Guide to OS/2 
appB 


0x0040 

Final character received (of double-byte character) 

0x0080 

Interim character received (of double-byte character) 

Values for fsState, which may be combined: 

Value 

Meaning 

0x0000 

Shift keys up 

0x0001 

Right Shift key down 

0x0002 

Left Shift key down 

0x0004 

Either Control key down 

0x0008 

Either Alt key down 

0x0010 

Scroll Lock turned on 

0x0020 

Num Lock turned on 

0x0040 

Caps Lock turned on 

0x0080 

Insert turned on 

0x0100 

Left Control key down 

0x0200 

Left Alt key down 

0x0400 

Right Control key down 

0x0800 

Right Alt key down 

0x1000 

Scroll Lock key down 

0x2000 

Num Lock key down 

0x4000 

Caps Lock key down 

0x8000 

Sys Req key down 


MouCiose 


♦ Purpose 

Closes the mouse device to a process. 

* Prototype 

unsigned int pascal far MouCiose 
(unsigned short MouseHandle); 

MoiiseHandle is the handle previously returned by MouOpen. 
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MouDeRegister 

♦ Purpose 

Deregisters a mouse subsystem for the screen group, restoring the default 
system. 


♦ Prototype 

unsigned int pascal far MouDeRegister 
(void); 

MouDrawPtr 

♦ Purpose 

Draws the mouse pointer on the screen, releasing any exclusion rectangle 
that may have been set through MouRemovePtr. 


♦ Prototype 

unsigned int pascal far MouDrawPtr 
(unsigned short MouseHandle); 


MouseHandle is the handle previously returned by MouOpen. 

MouFlushQue 

♦ Purpose 

Flushes mouse event queue. 


$ Prototype 

unsigned int pascal far MouFlushQue 
(unsigned short MouseHandle); 


MouseHandle is the handle previously returned by MouOpen. 


MouGetOevSIatus 


* Purpose 

Obtains device status of specified mouse. 

♦ Prototype 

unsigned int pascal far MouGetDevStatus 
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(unsigned intfar *PtrDefStatus, 

PtrOefStatus is a pointer to a variable to receive the device status, which 
may have any combination of the following values: 


Value 

Meaning 

0x0001 

Event queue engaged in I/O 

0x0002 

Block-read in progress 

0x0004 

Flush buffer in progress 

0x0008 

Pointer-draw function disabled because of unsupported 
mode 

0x0100 

Pointer-draw function disabled 

0x0200 

Mouse motion given in mickeys, not pixels 


unsigned short MouseHandle); 

MouseHandle is the handle previously returned by MouOpen. 


SVSouGetEventlVlask 

♦ Purpose 

Obtains the event mask for a mouse, that is, for what user actions the sys¬ 
tem generates mouse events. 

♦ Prototype 

unsigned int pascal far MouGetEventMask 
(unsigned intfar *PtrEvents, 

PtrEveiits is a pointer to a variable to receive the event mask, with any com¬ 
bination of the following values: 

Value Meaning 

0x0001 Mouse motion 

0x0002 Mouse motion with button-1-down events 

0x0004 Button-1-down events 

0x0008 Mouse motion with button-2-down events 

0x0010 Button-2-down events 

0x0020 Mouse motion with button-3-down events 

0x0040 Button-3-down events 
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unsigned short MouseHandle); 

MouseHandle is the handle previously returned by MouOpen. 


SViouGetHotKey 

♦ Purpose 

Gets button mask representing hotkey for mask. 

* Prototype 

unsigned int pascal far MouGetHotKey 
(unsigned int far * PtrButtons, 

PtrButtons is a pointer to a variable to receive the button mask, which may 
use any combination of these values to define the hotkey (if the first bit is 
set, no hotkey is defined): 


Value 

Meaning 

0x0001 

No button defined 

0x0002 

Button 1 

0x0004 

Button 2 

0x0008 

Button 3 


unsigned short MouseHandle): 

MouseHandle is a handle previously returned by MouOpen. 


MouGetNumBuftoins 

* Purpose 

Obtains number of buttons on current mouse. 

♦ Prototype 

unsigned int pascal far MouGetNumButtons 
(unsigned int far * PtrButtons, 

PtrButtons is a pointer to a variable to receive the number of buttons, 
unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 
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MouGetNumMickeys 

* Purpose 

Number of mickeys per centimeter for specified mouse. 

* Prototype 

unsigned int pascal far MouGetNumMickeys 
(unsigned int far *PtrMickeys, 

PtrMiekeys is a pointer to a variable to receive the number of mickeys. 
unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 


MouGetNumQueEl 


♦ Purpose 

Obtains number of events in the mouse event queue. 

♦ Prototype 

unsigned int pascal far MouGetNumQueEl 
(MOUQUEINFO far *PtrNumEvents, 

PtrNumEvents is a pointer to the MOUQUEINFO structure described 
below. 

unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 

♦ Structures 

typedef struct _MOUQUEINFO 

{ 

unsigned int cEvents; /* Current number of elements. */ 

unsigned int cmaxEvents; /* Maximum number of elements. */ 

} 

MOUQUEINFO; 


MouGetPtrPos 


❖ Purpose 

Obtains current screen coordinates of mouse pointer. 
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♦ Prototype 

unsigned int pascal far MouGetPtrPos 
(PTRLOC far *PtrPosition, 

PtrPosition is a pointer to the PTRLOC structure described below, 
unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 

* Structures 

typedef struct _PTRLOC 

{ 

unsigned int row; /* X-coordinate. */ 

unsigned int col; /* Y-coordinate. */ 

} 

PTRLOC; 


MouGeiPtrShape 

♦ Purpose 

Retrieves the bit masks that define the shape of the mouse pointer. 

* Prototype 

unsigned int pascal far MouGetPtrShape 
(unsigned char far *PtrBuffer, 

PtrBuffer is a pointer to a buffer to receive the masks. 

PTRSHAPE far *Ptrlnfo, 

Ptrlnfo is a pointer to the PTRSHAPE structure to receive information, 
unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 

❖ Structures 

typedef struct _PTRSHAPE 


{ 


unsigned int cb; 

/* Length of AND and XOR masks in bytes. 

*/ 

unsigned int col; 

/* Width of each mask. 

*/ 

unsigned int row; 

/* Height of each mask. 

*/ 

unsigned int colHot; 

/* Horizontal offset from upper left 

*/ 


/* corner of pointer to hot spot. 

*/ 
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unsigned int rowHot; /* Vertical offset from upper left */ 

/* corner of pointer to hot spot. */ 

} /* Measures are in character cells for */ 

PTRSHAPE; /* text and in pixels for graphics. */ 


MouGetScaleFact 


♦ Purpose 

Obtains horizontal and vertical scaling factors, that is, the number of mick- 
eys the mouse must travel to move the pointer one screen unit. 

♦ Prototype 

unsigned int pascal far MouGetScaleFact 
(SCALEFACT far *PtrFactors, 

PtrFactors is a pointer to the SCALEFACT structure described below, 
unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 

♦ Structures 

typedef struct _SCALEFACT 

{ 

unsigned int rowScale; /* Vertical scaling factor. */ 

unsigned int colScale; /* Horizontal scaling factor. */ 

} 

SCALEFACT; 


MoulnitReal 


♦ Purpose 

Initializes real mode mouse driver. 

♦ Prototype 

unsigned int pascal far MoulnitReal 
(char far *PtrDriverName); 

PtrDriverName is a pointer to the name of a pointer-draw driver. 


IVBouOpen 

♦ Purpose 

Opens mouse driver for current screen group. 
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* Prototype 

unsigned int pascal far MouOpen 
(char far *PtrDriverName, 

PtrDriverName is a pointer to the name of a pointer-draw driver, 
unsigned short far *PtrMouseHandle); 

PtrMouseHandle is a pointer to a variable to receive the mouse device handle. 


MouReadEventQue 

♦ Purpose 

Gets an event from a mouse event queue. 

♦ Prototype 

unsigned int pascal far MouReadEventQue 
(MOUEVENTINFOfar *PtrEvent, 

PtrEvent is a pointer to the MOUEVENTINFO structure described 
below. 

unsigned int far ‘PtrWait, 

PtrWait is a pointer to a variable specifying whether the function should wait 
for an event. If PtrWait is 1 and the queue is empty, set all MOUEVENT¬ 
INFO fields to 0 and return immediately. If PtrWait is 0, wait for mouse event. 

unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 

♦ Structures 

typedef struct _MOUEVENTINFO 

{ 

unsigned int fs; /* Action that caused event, as below. */ 

unsigned long Time; /* Time of day in milliseconds. *1 


unsigned int row; /* X-coordinate of mouse. *1 

unsigned int col; /* Y-coordinate of mouse. *1 

} /* Coordinate units as set by */ 

MOUEVENTINFO; /* MouSetDevStatus. */ 

Values of fs field, which may be combined: 


Value Meaning 

0x0000 No buttons down 

0x0001 Mouse moved with no buttons down 
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0x0002 

Mouse moved with button 1 down 

0x0004 

Button 1 down 

0x0008 

Mouse moved with button 2 down 

0x0010 

Button 2 down 

0x0020 

Mouse moved with button 3 down 

0x0040 

Button 3 down 


MouRegisfer 

♦ Purpose 

Registers a mouse subsystem for a given device. 

♦ Prototype 

unsigned int pascal far MouRegister 
(char far *PtrModuleName, 

PtrModuleName is a pointer to the name of a dynamic-link module con¬ 
taining the replacement functions. 

char far *PtrEntryName, 

PtrEntryName is a pointer to the name of an entry-point function to 
replace the default functions. 

unsigned long Functions); 

Functions specifies the functions to be replaced, from among the following: 


Value 

Meaning 

0x00000001 

Replace MouGetNumButtons 

0x00000002 

Replace MouGetNumMickeys 

0x00000004 

Replace MouGetDevStatus 

0x00000008 

Replace MouGetNumQueEl 

0x00000010 

Replace MouReadEventQue 

0x00000020 

Replace MouGetScaleFact 

0x00000040 

Replace MouGetEventMask 

0x00000080 

Replace MouSetScaleFact 

0x00000100 

Replace MouSetEventMask 

0x00000200 

Replace MouGetHotKey 
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0x00000400 

Replace MouSetHotKey 

0x00000800 

Replace MouOpen 

0x00001000 

Replace MouClose 

0x00002000 

Replace MouGetPtrShape 

0x00004000 

Replace MouSetPtrShape 

0x00008000 

Replace MouDrawPtr 

0x00010000 

Replace MouRemovePtr 

0x00020000 

Replace MouGetPtrPos 

0x00040000 

Replace MouSetPtrPos 

0x00080000 

Replace MouInitReal 

0x00100000 

Replace MouSetDevStatus 


♦ Comments 

The entry-point function must have this form: 

void far FuncName 
(unsigned int Reservedl, 

Reservedl must not be altered. 

unsigned int Function, 

Function specifies the function code identifying the function request, as 
follows: 


Value 

Meaning 

0x0000 

MouGetNumButtons called 

0x0001 

MouGetNumMickeys called 

0x0002 

MouGetDevStatus called 

0x0003 

MouGetNumQueEl called 

0x0004 

MouReadEventQue called 

0x0005 

MouGetScaleFact called 

0x0006 

MouGetEventMask called 

0x0007 

MouSetScaleFact called 

0x0008 

MouSetEventMask called 

0x0009 

MouGetHotKey called 

OxOOOA 

MouSetHotKey called 
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OxQOOB 

MouOpen called 

OxOOQC 

MouClose called 

OxOQOD 

MouGetPtrShape called 

QxOOOE 

MouSetPtrShape called 

OxOQOF 

MouDrawPtr called 

0x0010 

MouRemovePtr called 

0x0011 

MouGetPtrPos called 

0x0012 

MouSetPtrPos called 

0x0013 

MouInitReal called 

0x0014 

MouSetDevStatus called 


unsigned long Reserved2, 

Reserved! must not be altered. 

unsigned int Paraml, 
unsigned int Param2, 
unsigned int Param3, 
unsigned int Param4, 
unsigned int Param5); 

Paraml, ParamS specify up to five values passed with the original 
mouse function call. The number of parameters varies with the function 
called. 


MouRemovePtr 


♦ Purpose 

Removes a mouse pointer by creating an exclusion rectangle over part of 
the screen. 

♦ Prototype 

unsigned int pascal far MouRemovePtr 
(NOPTRRECT far *PtrRect, 

PtrRect is a pointer to the NOPTRRECT structure described below, 
unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 

♦ Structures 

typedef struct _NOPTRRECT 
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unsigned int row; /* 

unsigned int col; /* 

unsigned int cRow; /* 

unsigned int cCol; /* 

} /* 

NOPTRRECT; /* 


X-coordinate of upper left corner. */ 
Y-coordinate of upper left corner. */ 
X-coordinate of lower right corner. */ 
Y-coordinate of lower right corner. *1 
Units are in character cells for */ 
text, pixels for graphics. */ 


MouSetDevStatus 

❖ Purpose 

Sets device status for the given mouse device. 

♦ Prototype 

unsigned int pascal far MouSetDevStatus 
(unsigned int far * PtrDevStatus, 

PtrOevStatus is a pointer to a variable containing the status to be set, which 
may combine the following values: 

Value Meaning 

0x0100 Disable pointer-draw function, otherwise enable 

0x0200 Report mouse motion in mickeys moved, otherwise report in 
character cells or pixels from upper left of screen 

unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 


MouSetEventMask 

♦ Purpose 

Sets event mask for mouse device, that is, what user actions generate mouse 
events. 

♦ Prototype 

unsigned int pascal far MouSetEventMask 
(unsigned int far *PtrEvents, 

PtrEvents is a pointer to a variable to receive the event mask, to enable any 
combination of the following values: 

Value Meaning 

0x0001 Mouse motion 

0x0002 Mouse motion with button-1-down events 
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0x0004 Button-1-down events 

0x0008 Mouse motion with button-2-down events 
0x0010 Button-2-down events 
0x0020 Mouse motion with button-3-down events 
0x0040 Button-3-down events 

unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 


SVSouSetHotKey 

♦ Purpose 

Sets system hotkey on mouse for all screen groups, for use by the session 
manager. 

♦ Prototype 

unsigned int pascal far MouSetHotKey 
(unsigned int far *PtrButtons, 

PtrButtons is a pointer to a variable to receive the button mask, which may 
use any combination of these values to define the hotkey (if the first bit is 
set, no hotkey is defined): 


Value 

Meaning 

0x0001 

No button defined 

0x0002 

Button 1 

0x0004 

Button 2 

0x0008 

Button 3 


unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 


MouSetPtrPos 

^ Purpose 

Sets current mouse position, in character cells or pixels from the upper left 
corner of screen. 
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♦ Prototype 

unsigned int pascal far MouSetPtrPos 
(PTRLOCfar *PtrPosition, 

PtrPosition is a pointer to the PTRLOC structure described below, 
unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 

♦ Structures 

typedef struct _PTRLOC 

{ 

unsigned int row; /* X-coordinate. *1 

unsigned int col; /* Y-coordinate. *1 

} 

PTRLOC; 


MouSetPtrShape 

♦ Purpose 

Sets masks that define shape of mouse pointer. 

♦ Prototype 

unsigned int pascal far MouSetPtrShape 
(unsigned char far ‘PtrBuffer, 

PtrBuffer is a pointer to a buffer containing new masks. 

PTRSHAPE far ‘Ptrlnfo, 

Ptrlnfo is a pointer to the PTRSHAPE structure described below, 
unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 

♦ Structures 

typedef struct _PTRSHAPE 

{ 


unsigned int cb; /* Length of AND and XOR masks in bytes. */ 

unsigned int col; /* Width of each mask. */ 

unsigned int row; /* Height of each mask. */ 

unsigned int colHot; /* Horizontal offset from upper left */ 

/* corner of pointer to hot spot. */ 
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unsigned int rowHot; /* Vertical offset from upper left */ 

/ * corner of pointer to hot spot. * / 

} /* Measures are in character cells for */ 

PTRSHAPE; /* text and in pixels for graphics. */ 


MouSetScaleFact 


♦ Purpose 

Sets horizontal and vertical scaling factors, that is, the number of mickeys 
the mouse must travel to move the pointer one screen unit. 

♦ Prototype 

unsigned int pascal far MouSetScaleFact 
(SCALEFACT far *PtrFactors, 

PtrFactors is a pointer to the SCALEFACT structure described below, 
unsigned short MouseHandle); 

MouseHandle is a handle previously returned by MouOpen. 

♦ Structures 

typedef struct _SC ALE FACT 

{ 

unsigned int rowScale; /* Vertical scaling factor. */ 

unsigned int colScale; /* Horizontal scaling factor. */ 

} 

SCALEFACT; 


MouSynch 

* Purpose 

Synchronizes access to a mouse device, for use by a mouse subsystem. 

♦ Prototype 

unsigned int pascal far MouSynch 
(unsigned int Wait); 

If Wait is 0, return immediately; if Wait is 1, wait for mouse driver to 
become free. 
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VioDeRegister 

* Purpose 

Releases any previously registered video subsystem, restoring default video 
subsystem functions. 

♦ Prototype 

unsigned int pascal far VioDeRegister 
(void); 


VioEndPopUp 

♦ Purpose 

Closes a pop-up screen, restoring previous screen contents. 

♦ Prototype 

unsigned int pascal far VioEndPopUp 
(unsigned short VioHandle); 

VioHandle must be zero. 


VioGetAnsi 

❖ Purpose 

Obtains state of ANSI flag, finding whether VioWrtTTy will process ANSI 
sequences. 

♦ Prototype 

unsigned int pascal far VioGetAnsi 
(unsigned int far * PtrANSI, 

If PtrANSI is 0 5 ANSI is off; if PtrANSI is 1, ANSI is on. 

unsigned short VioHandle); 

VioHandle must be zero. 


VioGetBuf 

♦ Purpose 

Obtains address of logical video buffer for a process. 
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♦ Prototype 

unsigned int pascal far VioGetBuf 
(unsigned long far *PtrLVB, 

PtrLVB is a pointer to receive the selector for a logical video buffer, 
unsigned int far *PtrLVBLength, 

PtrLVBLength is a pointer to a variable that specifies the length of the logi¬ 
cal video buffer. 

unsigned short VioHandle); 

VioHandle must be zero. 


VioGetConfig 

♦ Purpose 

Obtains system display configuration. 

♦ Prototype 

unsigned int pascal far VioGetConfig 
(unsigned int Reserved, 

Reserved must be zero. 

VIOCONFIGINFO far *PtrConfig, 

PtrConfig is a pointer to the VIOCONFIGINFO structure described 
below. 

unsigned short VioFlandle); 

VioHandle must be zero. 

♦ Structures 

typedef struct _VIOCONFIGINFO 

{ 


unsigned int 

cb; 

/* Length of structure, set to OxOOOA. 

*/ 

unsigned int 

adapter; 

/* Adapter type, as below. 

*/ 

unsigned int 

display; 

/* Display type, as below. 

*/ 

unsigned long cbMemory; 

} 

VIOCONFIGINFO; 

/* Bytes of adapter memory. 

*/ 
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Values for adapter: 

Value 

Meaning 

0x0000 

Monochrome 

0x0001 

CGA 

0x0002 

EGA 

0x0003 

VGA or PS/2 

Values for display: 

Value 

Meaning 

0x0000 

Monochrome 

0x0001 

Color 

0x0002 

Enhanced color 

0x0003 

8503 monochrome 

0x0004 

8512, 8513, or 8514 


VioGstCp 

♦ Purpose 

Obtains code page for current display. 

* Prototype 

unsigned int pascal far VioGetCp 
(unsigned int Reserved, 

Reserved must be zero. 

unsigned int far *PtrCodePagelD, 

PtrCodePagelB is a pointer to a variable to receive code-page identifier. 

unsigned short VioHandle); 

YioHasidle must be zero. 


VioGetCurPos ~ 

♦ Purpose 

Returns current cursor position on screen. 
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♦ Prototype 

unsigned int pascal far VioGetCurPos 
(unsigned int far *PtrRow, 

PtrMow is a pointer to a variable to receive the current row position of cursor, 
unsigned int far *PtrColumn, 

PtrColiimn is a pointer to a variable to receive the current column position 
of cursor. 

unsigned short VioHandle); 

VioHandle must be zero. 


VioGetCurType 

♦ Purpose 

Returns information about cursor size and visibility. 

* Prototype 

unsigned int pascal far VioGetCurType 
(VIOCURSORINFO far ‘PtrCursor, 

PtrCursor is a pointer to the VIOCURSORINFO structure described 
below. 

unsigned short VioHandle); 


VioHandle must be zero. 

♦ Strustures 

typedef struct _VIOCURSORINFO 

{ 

unsigned int yStart; /* Top line of cursor, numbered from 0. *1 

unsigned int cEnd; /* Bottom line of cursor. */ 

unsigned int cx; /* Width in columns (text) or pixels */ 

/* (graphics). */ 

unsigned int attr; /* Of cursor; OxFFFF = hidden. */ 

} 

VIOCURSORINFO; 


VioGetFont 


* Purpose 

Retrieves either current font or a font from display ROM. 
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♦ Prototype 

unsigned int pascal far VioGetFont 
(VIOFONTINFO far *PtrFont, 

PtrFont is a pointer to the VIOFONTINFO structure described below. 

unsigned short VioHandle); 

VioHandle must be zero. 

* Structures 

typedef struct _VIOFONTINFO 


{ 

unsigned int 

cb; 

/* Length of structure, set to OxOOOE. 

*/ 

unsigned int 

type; 

/* 0 = current font; 1 = ROM font. 

*/ 

unsigned int 

cxCell; 

/* Width in pixels of character cell. 

*/ 

unsigned int 

cyCell; 

/* Height in pixels of character cell. 

*/ 

void far * 

; pbData; 

/* Pointer to buffer to receive table; 

*/ 



1*0 = function writes address here. 

*/ 

unsigned int 

cbData; 

/* Length in bytes of the font. 

*/ 

VIOFONTINFO; 





VioGetMode 

♦ Purpose 

Returns current screen mode. 

♦ Prototype 

unsigned int pascal far VioGetMode 
(VIOMODEINFO far *PtrMode, 

PtrMode is a pointer to the VIOMODEINFO structure described below. 

unsigned short VioHandle); 

VioHandle must be zero. 

♦ Structures 

typedef struct _VIOMODEINFO 

{ 

unsigned int cb; 
unsigned char fbType; 
unsigned char color; 
unsigned int col; 
unsigned int row; 


/* Length of structure, set to OxOOOE. */ 

/* Screen mode, values as below. */ 

/* Number of colors, as power of 2. */ 

/* Number of text columns. */ 

/* Number of text rows. */ 
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unsigned int 

hres; 

/* Number of pixel columns. 

*/ 

unsigned int 

vres; 

/* Number of pixel rows. 

*/ 

unsigned char 

fmt_ID; 

/* Reserved; must be zero. 

*/ 

unsigned char 
} 

VIOMODEINFO 

attrib; 

/* Reserved; must be zero. 

*/ 


Possible values for fbType: 


Value 

Meaning 

0x0000 

Monochrome enabled 

0x0001 

Other video adapter enabled 

0x0002 

Graphics mode enabled 

0x0004 

Color burst disabled 


VioGetPhysBuf 

♦ Purpose 

Returns a selector to the physical video buffer. 

♦ Prototype 

unsigned int pascal far VioGetPhysBuf 
(VIOPHYSBUFfar *PtrBuffer, 

PtrBuffer is a pointer to the VIOPHYSBUF structure described below. 

unsigned int Reserved); 

Reserved must be zero. 

♦ Structures 

typedef struct _VIOPHYSBUF 


{ 


unsigned char far *pBuf; 

/* 32-bit physical address of buffer, 

*/ 


/* from OxOOOAOOOO to OxOOOBFFFF. 

*! 

unsigned long cb; 

/* Length in bytes of video buffer 

*/ 

unsigned short asel[1 ]; 

/* Array to receive selectors for 

*/ 

} 

/* physical memory one per 64K bytes. 

*/ 

VIOPHYSBUF; 

/* Adjust array size as needed. 

*/ 
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VioGetState 


♦ Purpose 

Returns current settings for palette registers, border color, and blink/ 
background intensity switch. 

♦ Prototype 

unsigned int pascal far VioGetState 
(void far *PtrState, 

PtrState is a pointer to a structure to receive state information, which varies 
with request type. See below. 

unsigned short VioHandle); 

VioHandle must be zero. 


♦ Structures 

For palette registers: 


typedef struct _VIOPALSTATE 


unsigned int cb; /* Length of structure in bytes, 

unsigned int type; /* 0x0000 = palette register state, 

unsigned int First; /* First register to retrieve, from 

/* 0x0000 to OxOOOF. 

unsigned int acolorfl]; /* Include element for each register. 

} 

VIOPALSTATE; 


For border colors: 


typedef struct _VIOOVERSCAN 

unsigned int cb; /* Length of structure in bytes, 

unsigned int type; /* 0x0001 = overscan (border) color, 

unsigned int color; /* Color value. 

} 

VIOOVERSCAN; 

For blink/background intensity switch: 


typedef struct _VIOINTENSITY 

{ 

unsigned int cb; 


*/ 

*/ 

*/ 


*/ 


/* Length of structure in bytes. 
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unsigned int type; /* 0x0002 = blink/intensity switch. */ 

unsigned int fs; /* 0x0000 = blink; 0x0001 = intensity. */ 

} 

VIOINTENSITY; 


VioModeUntio 

♦ Purpose 

Cancels a request to be informed of a video mode change (made via Vio- 
ModeWait), or gives up ownership of such a request (which is restricted to 
one process per screen group). 

♦ Prototype 

unsigned int pascal far VioModeUndo 
(unsigned int Relinquish, 

If Relinquish is 0, retain ownership; if Relinquish is 1, relinquish owner¬ 
ship. 

unsigned int Terminate, 

If Terminate is 0, VioModeWait returns error to calling thread, which con¬ 
tinues; if Terminate is 1, thread is terminated. 

unsigned int VioHandle); 

VioHandSe must be zero. 


VioModeWait 


♦ Purpose 

Blocks until video mode changes, then reports type of change. Used to 
notify that pop-up has cleared. 

♦ Prototype 

unsigned int pascal far VioModeWait 
(unsigned int Event, 

If Event is 0, wait for pop-up to clear; no other values used, 
unsigned int far * PtrNotify, 

PtrNotify points to a variable that receives a code indicating the action to 
be carried out. Currently, 0 is the only value assigned, which means to 
restore the video mode. 
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unsigned int VioHandle); 

VioHandle must be zero. 


VioPopUp 

♦ Purpose 

Opens a pop-up screen. 

❖ Prototype 

unsigned int pascal far VioPopUp 
(unsigned int far *PtrWait, 

PtrWait specifies whether to wait for prior pop-up to close; specifies 
whether to preserve existing screen, with a combination of the following 
values: 


Value Meaning 

0x0000 Return immediately if already a pop-up 

0x0001 Wait for existing pop-up to clear 

0x0000 Change screen mode to 80 x 25 text and clear screen 

0x0002 Do not change mode, clear screen, or move cursor; fail if 
unable to comply 

unsigned short VioHandle); 

VioHandle must be zero. 


VioPrtSc 

* Purpose 

Prints a screen in response to Shift-PrtSc key combination. Reserved for 
system use, but a substitute function may be designated through VioRegis- 
ter that will run at system privilege level. 

♦ Prototype 

unsigned int pascal far VioPrtSc 
(unsigned short VioHandle); 


VioHandle must be zero. 
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VioPrfScToggie 

♦ Purpose 

Toggles screen echo to printer in response to Control-PrtSc key combina¬ 
tion. Reserved for system use, but a substitute function may be designated 
through VioRegister that will run at system privilege level. 

♦ Prototype 

unsigned int pascal far VioPrtScToggle 
(unsigned short VioHandle); 

VioHandle must be zero. 


VioReadCellStr 

♦ Purpose 

Reads a sequence of character-attribute pairs from the screen. 

♦ Prototype 

unsigned int pascal far VioReadCellStr 
(char far *PtrCellString, 

PtrCellString is a pointer to a buffer to receive a string, 
unsigned int far *PtrBufferLength, 

PtrBufferLength is a pointer to the number of bytes to read. Should be 
even. Function returns number of bytes actually read here. 

unsigned int Row, 

Row is the starting row. 

unsigned int Column, 

Column is the starting column. 

unsigned short VioHandle); 

VioHandle must be zero. 


VioReadCharStr 


♦ Purpose 

Reads a character string from the screen from a given location. 



Summary of the API 


♦ Prototype 

unsigned int pascal far VioReadCharStr 
(char far * PtrString, 

PtrString is a pointer to a buffer to receive the string, 
unsigned int far *PtrBufferLength, 

PtrBufferLength is a pointer to a variable holding the length of string to 
copy. Function returns the length actually copied here. 

unsigned int Row, 

Row is the starting row. 

unsigned int Column, 

Column is the starting column. 

unsigned short VioHandle); 

VioHandle must be zero. 


VioBegisler 

♦ Purpose 

Registers an alternate video subsystem within a screen group, replacing one 
or more default video functions. 

❖ Prototype 

unsigned int pascal far VioRegister 
(char far ‘PtrModuleName, 

PtrModuleName is a pointer to the name of a dynamic-link module to be 
used. 

char far *PtrEntryName, 

PtrEntryName is a pointer to the name of an entry-point function, 
unsigned long Functionl, 

Function! specifies the video functions to be replaced. It can be any combi¬ 
nation of the following values: 

Value Meaning 

0x00000001 Replace VioGetCurPos 

0x00000002 Replace VioGetCurType 



0x00000004 

Replace VioGetMode 

0x00000008 

Replace VioGetBuf 

0x00000010 

Replace VioGetPhysBuf 

0x00000020 

Replace VioSetCurPos 

0x00000040 

Replace VioSetCurType 

0x00000080 

Replace VioSetMode 

0x00000100 

Replace VioShowBuf 

0x00000200 

Replace VioReadCharStr 

0x00000400 

Replace VioReadCellStr 

0x00000800 

Replace VioWrtNChar 

0x00001000 

Replace VioWrtNAttr 

0x00002000 

Replace VioWrtNCell 

0x00004000 

Replace VioWrtTTy 

0x00008000 

Replace VioWrtCharStr 

0x00010000 

Replace VioWrtCharStrAttr 

0x00020000 

Replace VioWrtCellStr 

0x00040000 

Replace VioScrollUp 

0x00080000 

Replace VioScrollDn 

0x00100000 

Replace VioScrollLf 

0x00200000 

Replace VioScrollRt 

0x00400000 

Replace VioSetAnsi 

0x00800000 

Replace VioGetAnsi 

0x01000000 

Replace VioPrtSc 

0x02000000 

Replace VioScrLock 

0x04000000 

Replace VioScrUnLock 

0x08000000 

Replace VioSavRedrawWait 

0x10000000 

Replace VioSavRedrawUndo 

0x20000000 

Replace VioPopUp 

0x40000000 

Replace VioEndPopUp 

0x80000000 

Replace VioPrtScToggle 
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unsigned long Function2); 

Function! specifies further video functions to be replaced. It can be any 


combination of the following values: 

Value 

Meaning 

0x00000001 

Replace YioModeWait 

0x00000002 

Replace VioModeUndo 

0x00000004 

Replace VioGetFont 

0x00000008 

Replace VioGetConfig 

0x00000010 

Replace VioSetCp 

0x00000020 

Replace VioGetCp 

0x00000040 

Replace VioSetFont 

0x00000080 

Replace VioGetState 

0x00000100 

Replace VioSetState 


♦ Comments 

The entry-point function that you write must have this form: 

void far FuncName 
(unsigned short DataSeg, 

DataSeg is the data-segment selector of the process calling the video function. 

unsigned int Reservedl, 

Eeservedl must not be altered, 
unsigned int Function, 

Function may be any of the following values: 


Value 

Meaning 

0x0000 

VioGetPhysBuf 

0x0001 

VioGetBuf 

0x0002 

VioShowBuf 

0x10003 

VioGetCurPos 

0x0004 

VioGetCurType 

0x0005 

VioGetMode 
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0x0006 

VioSetCurPos 

0x0007 

VioSetCurType 

0x0008 

VioSetMode 

0x0009 

VioReadCharStr 

OxOOOA 

VioReadCellStr 

OxOOOB 

VioWrtNChar 

OxOOOC 

VioWrtNAttr 

OxOOOD 

VioWrtNCell 

OxOOOE 

VioWrtCharStr 

OxOOOF 

VioWrtCharStrAttr 

0x0010 

VioWrtCellStr 

0x0011 

VioWrtTTy 

0x0012 

VioScrollUp 

0x0013 

VioScrollDn 

0x0014 

VioScrollLf 

0x0015 

VioScrollRt 

0x0016 

VioSetAnsi 

0x0017 

VioGetAnsi 

0x0018 

VioPrtSc 

0x0019 

VioScrLock 

0x001A 

VioScrUnLock 

0x001B 

VioSavRedrawWait 

0x001C 

VioSavRedrawUndo 

0x00 ID 

VioPopUp 

0x00IE 

VioEndPopUp 

0x00IF 

YioPrtScToggle 

0x0020 

VioModeWait 

0x0021 

VioModeUndo 

0x0022 

VioGetFont 

0x0023 

VioGetConfig 

0x0024 

VioSetCp 

0x0025 

VioGetCp 
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0x0026 VioSetFont 
0x0027 VioGetState 
0x0028 VioSetState 
unsigned long Reserved2, 

Reserved! must not be altered. 

unsigned int Paraml, 
unsigned int Param2, 
unsigned int Param3, 
unsigned int Param4, 
unsigned int Param5, 
unsigned int Param6); 

Paraml, ..., Param6 specify up to six values passed with the original call. 

The number of parameters may vary with the function. 


VioSavRedrawUndo 

♦ Purpose 

Cancels the effects of a VioSavRedrawWait call. Cancels the call and either 
terminates the calling thread or allows it to continue. May relinquish own¬ 
ership of the request. 

* Prototype 

unsigned int pascal far VioSavRedrawUndo 
(unsigned int Relinquish, 

If Relinqisfa is 0, retain ownership; if Relinquish is 1, release ownership, 
unsigned int Terminate, 

If Terminate is 0, VioSavRedrawWait returns error code and thread may 
continue; if Terminate is 1, thread terminates. 

unsigned int VioHandle); 

VioHandle must be zero. 


VioSavRedrawWait 

* Purpose 

Blocks and awaits a screen switch. Typically called by thread that saves 
graphic screen information before a screen switch and restores it after its 
screen group is returned to the foreground. 
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♦ Prototype 

unsigned int pascal far VioSavRedrawWait 
(unsigned int Event, 

If Event is 0, return when screen is to be either saved or redrawn; if Event is 
1, return only when screen needs to be redrawn. 

unsigned int far *PtrNotify, 

PtrNotify is a pointer to a variable to receive flags specifying either of these 
actions: 

Value Meaning 

0x0000 Save screen buffer, registers, and state information 
0x0001 Restore screen buffer, registers, and state information 
unsigned int Reserved): 

Reserved must be zero. 


VioScrLock 


♦ Purpose 

Locks the physical screen buffer, indicating that it is in use (only one process 
can have it locked at a given time). 

♦ Prototype 

unsigned int pascal far VioScrLock 
(unsigned int Wait, 

If Wait is 0, return immediately even if screen not available; if Wait is 1, 
wait for screen to become available. 

unsigned char far *PtrNotLocked, 

PtrNotLocked is a pointer to a variable to receive a value specifying if 
screen is locked. Value 0 means locked (success); value 1 means not locked. 

unsigned short VioHandle); 

VioHandle must be zero. 


VioScrollDn 


♦ Purpose 

Scrolls an area of the screen down, reading in new cells at the top row. 



Summary of the API 


* Prototype 

unsigned int pascal far VioScrollDn 
(unsigned int TopRow, 

TopRow is the top row of the area to scroll; use 0 to scroll screen, 
unsigned int LeftCol, 

LeftCol is the left column of the area to scroll; use 0 to scroll screen, 
unsigned int BotRow, 

BotRow is the bottom row of the area to scroll; use - 1 to scroll screen, 
unsigned int RightCol, 

RightCol is the right column of the area to scroll; use - 1 to scroll screen. 

unsigned int Lines, 

Lines is the number of rows to scroll; use - 1 to clear area, 
unsigned char far * PtrCell, 

PtrCell is a pointer to a cell (two-element array) to write to new rows. 

unsigned short VioHandle); 

VioHandle must be zero. 


VioScrolILf 

♦ Purpose 

Scrolls an area of the screen left, reading in new cells at the right column. 

♦ Prototype 

unsigned int pascal far VioScrolILf 
(unsigned int TopRow, 

TopRow is the top row of the area to scroll; use 0 to scroll screen, 
unsigned int LeftCol, 

LeftCol is the left column of the area to scroll; use 0 to scroll screen, 
unsigned int BotRow, 

BotRow is the bottom row of the area to scroll; use - 1 to scroll screen, 
unsigned int RightCol, 

RightCol is the right column of the area to scroll; use - 1 to scroll screen. 
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unsigned int Columns, 

Columns is the number of columns to scroll; use - 1 to clear area, 
unsigned char far * PtrCell, 

PtrCell is a pointer to a cell (two-element array) to write to new columns. 

unsigned short VioHandle); 

VioHandle must be zero. 


VIoSeroIIRt 

♦ Purpose 

Scrolls an area of the screen right, reading in new cells at the left column. 

♦ Prototype 

unsigned int pascal far VioScrolIRt 
(unsigned int TopRow, 

TopRow is the top row of the area to scroll; use 0 to scroll screen. 

unsigned int LeftCol, 

LeftCol is the left column of the area to scroll; use 0 to scroll screen. 

unsigned int BotRow, 

BotRow is the bottom row of the area to scroll; use - 1 to scroll screen. 

unsigned int RightCol, 

RightCol is the right column of the area to scroll; use - 1 to scroll screen. 

unsigned int Columns, 

Columns is the number of columns to scroll; use - 1 to clear area, 
unsigned char far * PtrCell, 

PtrCell is a pointer to a cell (two-element array) to write to new columns. 

unsigned short VioHandle); 

VioHandle must be zero. 


VioScrolIUp 

♦ Purpose 

Scrolls an area of the screen up, reading in new cells at the bottom row. 
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♦ Prototype 

unsigned int pascal far VioScrollUp 
(unsigned intTopRow, 

TopRow is the top row of the area to scroll; use 0 to scroll screen, 
unsigned int LeftCol, 

LeftCoI is the left column of the area to scroll; use 0 to scroll screen, 
unsigned int BotRow, 

BotRow is the bottom row of the area to scroll; use — 1 to scroll screen, 
unsigned int RightCol, 

MightCoI is the right column of the area to scroll; use - 1 to scroll screen, 
unsigned int Lines, 

Lines is the number of rows to scroll; use - 1 to clear area, 
unsigned char far *PtrCell, 

PtrCel! is a pointer to a cell (two-element array) to write to new rows, 
unsigned short VioHandle); 

VioHandle must be zero. 


VioScrUnlock 

♦ Purpose 

Unlocks a previously locked screen. 

♦ Prototype 

unsigned int pascal far VioScrUnLock 
(unsigned short VioHandle); 

VioHandle must be zero. 


VioSetAnsi 

♦ Purpose 

Turns processing of ANSI control sequences on or off for a screen group. 

♦ Prototype 

unsigned int pascal far VioSetAnsi 
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(unsigned int Ansi, 

If Ansi is 0, turn ANSI off; if Ansi is 1, turn ANSI on. 

unsigned short VioHandle); 

VioHandle must be zero. 


VioSefCp 

♦ Purpose 

Sets the code page for a screen group. 

♦ Prototype 

unsigned int pascal far VioSetCp 
(unsigned int Reserved, 

Reserved must be zero. 

unsigned int CodePagelD, 

CodePagelB is any identifier given with the CODEPAGE directive 
CONFIG.SYS. Value 0x0000 means use default system code page. 

unsigned short VioHandle); 

VioHandle must be zero. 


VioSetCurPos 

♦ Purpose 

Sets the screen position of the hardware cursor. 

♦ Prototype 

unsigned int pascal far VioSetCurPos 
(unsigned int Row, 

Row is the row position, where 0 is the upper left corner, 
unsigned int Column, 

Column is the column position, where 0 is the upper left corner. 

unsigned short VioHandle); 

VioHandle must be zero. 
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VioSetCurType 

♦ Purpose 

Sets size of hardware cursor. 

♦ Prototype 

unsigned int pascal far VioSetCurType 
(VIOCURSORINFO far *PtrVioCursor, 

PtrVioCursor is a pointer to the VIOCURSORINFO structure described 
below. 

unsigned short VioHandle); 

VioHandle must be zero. 


♦ Structures 

typedef struct _VIOCURSORINFO 

{ 

unsigned int yStart; /* Top line of cursor, numbered from 0. */ 

unsigned int cEnd; /* Bottom line of cursor. *1 

unsigned int cx; /* Width in columns (text) or pixels *1 

I* (graphics). */ 

unsigned int attr; /* Of cursor; OxFFFF = hidden. */ 

} 

VIOCURSORINFO; 


VioSetFont 

♦ Purpose 

Assigns a font to display characters on the screen. Font size must match cur¬ 
rent screen mode. 

♦ Prototype 

unsigned int pascal far VioSetFont 
(VIOFONTINFO far ‘PtrFont, 

PtrFont is a pointer to the VIOFONTINFO structure described below. 

unsigned short VioHandle); 

VioHandle must be zero. 

♦ Structures 

typedef struct _VIOFONTINFO 

{ 
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unsigned 

int 

cb; 

/* Length of structure, set to OxOOOE. 

*/ 

unsigned 

int 

type; 

/* 0 = current font; 1 = ROM font. 

*/ 

unsigned 

int 

cxCell; 

/* Width in pixels of character cell. 

*/ 

unsigned 

int 

cyCell; 

/* Height in pixels of character cell. 

*/ 

void far 


* pbData; 

/* Pointer to buffer to receive table; 

*/ 




/* 0 = function to write address here. 

*/ 

unsigned 

int 

cbData; 

/* Length in bytes of the font. 

*/ 


} 

VIOFONTINFO; 


VioSetMode 


♦ Purpose 

Sets display mode, number of colors, and screen dimensions. 

♦ Prototype 

unsigned int pascal far VioSetMode 
(VIOMODEINFO far *PtrMode, 

PtrMode is a pointer to the VIOMODEINFO structure described below. 


unsigned short VioHandle); 
VioHaiidle must be zero. 

♦ Structures 


typedef struct _VIOMODEINFO 
{ 


unsigned int 

cb; 

1* 

unsigned char 

fbType; 

/* 

unsigned char 

color; 

/* 

unsigned int 

col; 

1* 

unsigned int 

row; 

/* 

unsigned int 

hres; 

/* 

unsigned int 

vres; 

1* 

unsigned char 

fmtJD; 

1* 

unsigned char 
\ 

attrib; 

1* 

j 

VIOMODEINFO; 




Possible values for ffoType: 
Value Meaning 


Length of structure, set to OxOOOE. */ 
Screen mode, values as below. */ 

Number of colors, as power of 2. */ 

Number of text columns. */ 

Number of text rows. */ 

Number of pixel columns. */ 

Number of pixel rows. */ 

Reserved; must be zero. */ 

Reserved; must be zero. */ 


0x0000 Monochrome enabled 
0x0001 Other video adapter enabled 
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0x0002 Graphics mode enabled 
0x0004 Color burst disabled 


VioSetState 

♦ Purpose 

Sets palette-register values, border color, or blink/background intensity 
switch. 

♦ Prototype 

unsigned int pascal far VioSetState 
(void far * PtrState, 

PtrState is a pointer to one of the three types of structures shown below, 
depending on the type of call. 

unsigned short VioHandle); 

VioHandle must be zero. 

♦ Structures 

For palette registers: 

typedef struct _VIOPALSTATE 

{ 

unsigned int cb; /* Length of structure in bytes. */ 

unsigned int type; /* 0x0000 = palette register state. */ 

unsigned int First; /* First register to retrieve, from */ 

/* 0x0000 to OxOOOF. */ 

unsigned int acolor[1]; /* Include element for each register. */ 

} 

VIOPALSTATE; 

For border colors: 

typedef struct _VIOOVERSCAN 

{ 

unsigned int cb; /* Length of structure in bytes. *1 

unsigned int type; /* 0x0001 = overscan (border) color. */ 

unsigned int color; /* Color value. */ 

} 

VIOOVERSCAN; 

For blink/background intensity switch: 

typedef struct _VIOINTENSITY 

{ 



528 


Programmer’s 
Guide to OS/2 
appB 


unsigned int cb; 

/* Length of structure in bytes. 

*/ 

unsigned int type; 

/* 0x0002 = blink/intensity switch. 

*/ 

unsigned int fs; 

X 

/* 0x0000 = blink; 0x0001 = intensity 

*/ 

/ 

VIOINTENSITY; 




VioShowBuf 

♦ Purpose 

Updates the physical screen from the logical video buffer. 

♦ Prototype 

unsigned int pascal far VioShowBuf 
(unsigned int LVBOffset, 

LVBOffset is the offset into the logical video buffer from which to begin, 
unsigned int Output, 

Output is the length in bytes of the area to be updated. 

unsigned short VioHandle); 

VioHandle must be zero. 


VfoWrtCellStr 

♦ Purpose 

Writes an array of character-attribute pairs to the screen. 

♦ Prototype 

unsigned int pascal far VioWrtCellStr 
(char far *PtrCellString, 

PtrCellString is a pointer to a cell string. 

unsigned int CellStringLength, 

CellStringLength is the number of bytes to write, which should be even. 

unsigned int Row, 

Row is the starting row. 

unsigned int Column, 

Column is the starting column. 
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unsigned short VioHandle); 

VioHandle must be zero. 


VioWrtCharStr 

❖ Purpose 

Writes a character string to the screen, preserving existing attributes. 

❖ Prototype 

unsigned int pascal far VioWrtCharStr 
(char far * PtrString, 

PtrString is a pointer to a string, 
unsigned int StringLength, 

StringLength is the number of bytes to write, 
unsigned int Row, 

Row is the starting row. 
unsigned int Column, 

Column is the starting column, 
unsigned short VioHandle); 

VioHandle must be zero. 


VioWrtGharStrAtt 

♦ Purpose 

Writes a character string to the screen, using a given attribute. 

♦ Prototype 

unsigned int pascal far VioWrtCharStrAtt 
(char far * PtrString, 

PtrString is a pointer to a string. 

unsigned int StringLength, 

StringLength is the number of bytes to write. 

unsigned int Row, 

Row is the starting row. 
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unsigned int Column, 

Column is the starting column, 
unsigned char far *PtrAttr 

PtrAttr is a pointer to a variable containing an attribute. 

unsigned short VioHandle); 

VioHandle must be zero. 


VIoWrtHAttr 

♦ Purpose 

Writes an attribute to the screen a stated number of times, leaving charac¬ 
ters unchanged. 

♦ Prototype 

unsigned int pascal far VioWrtNAttr 
(unsigned char far * PtrAttr, 

PtrAttr is a pointer to a variable containing an attribute, 
unsigned int Count, 

Count is the number of times to write, 
unsigned int Row, 

Row is the starting row. 
unsigned int Column, 

Column is the starting column, 
unsigned short VioHandle); 

VioHandle must be zero. 


VioWrtNCell 


* Purpose 

Writes a cell to the screen a given number of times. 

* Prototype 

unsigned int pascal far VioWrtNCell 
(unsigned char far * PtrCell, 

PtrCell is a pointer to a cell to be written, a two-byte array. 
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unsigned int Count, 

Count is the number of times to write. 

unsigned int Row, 

Row is the starting row. 

unsigned int Column, 

Column is the starting column. 

unsigned short VioHandle); 

VioHandle must be zero. 


VioWrtNChar 

❖ Purpose 

Writes a character to the screen a given number of times, preserving existing 
attributes. 

♦ Prototype 

unsigned int pascal far VioWrtNChar 
(char far *PtrChar, 

PtrChar is a pointer to a character to be written. 

unsigned int Count, 

Count is the number of times to write. 

unsigned int Row, 

Row is the starting row. 

unsigned int Column, 

Column is the starting column. 

unsigned short VioHandle); 

VioHandle must be zero. 


VioWrtTTy 

♦ Purpose 

Writes a character to the screen, recognizing ANSI sequences if enabled and 
responding to control characters, such as backspace (0x08). 
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♦ Prototype 

unsigned int pascal far VioWrtTTy 
(char far * PtrString, 

PtrString is a pointer to the string to write. Certain characters are treated 
specially, as follow: 

Value Meaning 

0x08 Move cursor left one column, without deleting any 

characters; if at leftmost column, do nothing 

0x09 Write spaces from current column to next 8-column tab stop 

OxOA Move cursor down one line; if at bottom of screen, scroll up 

OxOD Move cursor to beginning of line 

0x07 Generate a beep 

unsigned int StringLength, 

StringLength is the number of bytes to write. 

unsigned short VioHandle); 

VioHandle must be zero. 






APPENDIX C 


Input/ Output 
Control 
Functions 


This appendix summarizes the input-and-output control functions 
provided by OS/2. Chapter 4, in the section entitled Using Direct 
Device Control, describes how to use these functions and provides an 
example program. The input-and-output control functions communi¬ 
cate directly with the device driver, and are all accessed though the 
DosDevIOCtl API function. 

Note that this summary contains two types of structure descrip¬ 
tions: those that use the typedef keyword and have both a tag name 
and type name, and those that provide only a tag name. The typedef 
structures are contained within the standard OS/2 header files, and 
therefore you do not need to define them in your program. The struc¬ 
tures containing only tag names, however, are not contained within 
the header files and therefore you must define them in your program. 
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Category 01 h, 
Function 41h: 
Set Baud Bate 


♦ Purpose 

Sets the baud rate for a given serial device. 


♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrBaud, 0x0041,0x0001, DevHandle) 


Parameter Meaning 

unsigned int far *PtrBaud Bits per second, to 19200 

unsigned short DevHandle Handle previously returned by DosOpen 


Category 01 h, 
Function 42h: 
Set Line Control 
Register 


Parameter Meaning 

unsigned char far *PtrLineCtrl Pointer to structure described below 

unsigned short DevHandle Handle previously returned by 

DosOpen 

♦ Structures 

struct LineCtrl 

{ 

unsigned char DataBits; /* Number of data bits, from 5 to 8. */ 

unsigned char Parity; /* Parity, as shown below. */ 

unsigned char StopBits; /* Number of stop bits, as shown below. */ 

}; 

Values for Parity: 

Value Meaning 
0x00 No parity 
0x01 Odd parity 


♦ Purpose 

Sets data bits, stop bits, and parity of a serial device. 

* Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrLineCtrl, 0x0042, 0x0001, 
DevHandle) 
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Category 01 h, 
Function 44h: 
Transmit 
Immediately 


Category 01 h, 
Function 45h: 
Set Break Oft 


0x02 

Even parity 

0x03 

Mark parity 

0x04 

Space parity 


Values for StopBits: 

Value Meaning 

OxOO 1 stop bit 

0x01 1.5 stop bits, for 5-bit words 

0x02 2 stop bits, for other than 5-bit words 


♦ Purpose 

Transmits a byte ahead of any in the transmit queue. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrChar. 0x0044, 0x0001, DevHandle) 

Parameter Meaning 

unsigned char far *PtrChar Pointer to character to transmit 
unsigned short DevHandle Handle previously returned by DosOpen 


♦ Purpose 

Prevents the device from generating a break character. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (PtrCommErr , 0L, 0x0045, 0x0001, 
DevHandle) 


Parameter Meaning 

unsigned int far *PtrComtnErr Pointer to variable to receive status, 

which may combine the values shown 
below 

unsigned short DevHandle Handle previously returned by 

DosOpen 
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Values for PtrCommErr : 

Value Meaning 

0x0001 Receive character overrun: no room to read character from 
receive hardware 

0x0002 Receive hardware overrun: character received before 
preceding character read 

0x0004 Parity error 

0x0008 Framing error 


Category 01 h, 
Function 46h: 
Set Modem 
Control 


♦ Purpose 

Controls the DTR and RTS signals. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl {PtrCommErr, PtrCtrlSignals, 0x0046, 
0x0001, DevHandle) 


Parameter 

unsigned int far *PtrCommErr 

unsigned char far *PtrCtrlSignals 
unsigned short DevHandle 


Meaning 

Pointer to character to receive 
communications status, which may 
combine the values shown below 

Pointer to structure described 
below 

Handle previously returned by 
DosOpen 


Values for ^PtrCommErr: 


Value 

Meaning 

0x0001 

Receive character overrun: no room to read character from 
receive hardware 

0x0002 

Receive hardware overrun: character received before 
preceding character read 

0x0004 

Parity error 

0x0008 

Framing error 



Category 01 h, 
Function 47h: 
Stop Transmit 


Category 01 h, 
Function 48h: 
Start Transmit 
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♦ Structures 

struct CtrlSignals 

unsigned char ModemOn; /* Modem signals to be enabled, as below. */ 

unsigned char ModemOff; /* Signals to be disabled, as below. *1 

}; 

Values for ModemOn: 


Value 

Meaning 

0x00 

Enable no signals 

0x01 

Enable DTR 

0x02 

Enable RTS 

Values for ModemOff: 

Value 

Meaning 

OxFF 

Disable no signals 

OxFE 

Disable DTR 

OxFD 

Disable RTS 


♦ Purpose 

Stops a serial device from transmitting. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, OL, 0x0047, 0x0001, DevHandle) 

Parameter Meaning 

unsigned short DevHandle Handle previously returned by DosOpen 


♦ Purpose 

Allows a serial device to resume transmission after being stopped by Stop 
Transmit or receipt of an XOFF character. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, 0L, 0x0048, 0x0001, DevHandle) 



540 


Programmer’s 
Guide to OS/2 
appC 


Parameter Meaning 

unsigned short DevHandle Handle previously returned by DosOpen 


Category 01 h, 
Function 4Bh: 
Set Break On 


❖ Purpose 

Causes device driver to begin generating a break si gn al 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrCommErr , OL, 0x004B, 0x0001, 
DevHandle) 

Parameter Meaning 

unsigned int far *PtrCommErr Pointer to character to receive 

communications status, which may 
combine the values shown below 

unsigned short DevHandle Handle previously returned by 

DosOpen 


Values for * PtrCommErr: 

Value Meaning 

0x0001 Receive character overrun: no room to read character from 
receive hardware 

0x0002 Receive hardware overrun: character received before 
preceding character read 

0x0004 Parity error 

0x0008 Framing error 


Category 01 h, 

Function §3h: ♦ purpose 

Set DCB info Sets device-control information. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrDCB, 0x0053, 0x0001, DevHandle) 

Parameter Meaning 

unsigned int far *PtrDCB Pointer to structure described below 

unsigned short DevHandle Handle previously returned by DosOpen 
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♦ Structures 

struct DCB 

{ 

unsigned int WriteTimeout; /* Timeout in hundredths of second, minus 1. */ 

unsigned int ReadTimeOut; /* Timeout in hundredths of second, minus 1. */ 

unsigned char Flagsl; /* Control and handshaking modes, as below. */ 


unsigned char Flags2; /* Flow control modes, as below. */ 

unsigned char Flags3; /* Timeout processing, as below. *1 

unsigned char ErrorReplacementChar; /* Error replacement character. */ 
unsigned char BreakReplacementChar; /* Break replacement character. */ 
unsigned char XONChar; /* XON character, */ 

unsigned char XOFFChar; /* XOFF character. */ 

}; 


Values for Flagsl, some of which may be combined: 

Value Meaning 

0x01 Enable DTR; with this and following clear, DTR is disabled 

0x02 Enable DTR input handshaking mode; DTR controlled 
through device driver 

0x03 Reserved 

0x04 Reserved 

0x08 Enable CTS output handshaking 

0x10 Enable DSR output handshaking 

0x20 Enable DCD output handshaking 

0x40 Enable DSR input sensitivity, so input is lost if DSR is clear 
0x80 Reserved 

Values for FIag§2, some of which may be combined: 

Value Meaning 

0x01 Enable automatic XON/XOFF transmit flow control 

0x02 Enable automatic XON/XOFF receive flow control 

0x04 Enable error replacement character 

0x08 Enable null stripping 

0x10 Enable break replacement character 

0x20 Reserved 
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0x40 Enable RTS control mode 

0x80 Enable RTS input handshaking mode; RTS controlled through 
device driver 

OxCO Enable toggling on transmit mode; RTS will be on when there 
is data to transmit 

Values for F!ags3, which may combine a write timeout value with a read 
timeout value: 

Value Meaning 

0x01 Enable write infinite timeout 

0x02 Enable normal read timeout 

0x04 Enable wait-for-something read timeout 

0x06 Enable no-wait read timeout 


Category Olh, 
Function 61 h: 
Get Baud Rate 


♦ Purpose 

Gets the baud rate for a given serial device. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrBaudRate , 0L, 0x0061,0x0001, 
DevHandle) 

Parameter Meaning 

unsigned int far *PtrBaudRate Pointer to variable to receive baud 

rate 

unsigned short DevHandle Handle previously returned by 

DosOpen 


Category Olh, 
Function @2h: 
Get Line Control 


♦ Purpose 

Returns data bits, stop bits, parity, and break-character status for a device. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrLineCtrl , 0L, 0x0062, 0x0001, 

DevHandle) 
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Category 01 Si, 
Function B4h: 

Get Comm Status 


Parameter 

unsigned char far *PtrLineCtrl 
unsigned short DevHandle 

* Structures 

struct LineCtrl 

{ 

unsigned char DataBits; 
unsigned char Parity; 
unsigned char StopBits; 
unsigned char TransBreak; 

}; 

Values for Parity: 


Value 

Meaning 

0x00 

No parity 

0x01 

Odd parity 

0x02 

Even parity 

0x03 

Mark parity 

0x04 

Space parity 


Values for StopBits: 


Meaning 

Pointer to structure described below 

Handle previously returned by 
DosOpen 


/* Number of data bits, from 5 to 8. */ 

/* Parity, as shown below. */ 

/* Number stop bits, as shown below. */ 
/* Set if break being transmitted. */ 


Value Meaning 

0x00 1 stop bit 

0x01 1.5 stop bits, for 5-bit words 

0x02 2 stop bits, for other than 5-bit words 


♦ Purpose 

Retrieves status of a serial device. 

❖ Calling Protocol 

unsigned int pascal far DosDevlOCt! ( PtrStatus , 0L, 0x0064, 0x0001, DevHandle) 
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Parameter Meaning 

unsigned char far *PtrStatus Pointer to variable with a combination 

of the values shown below 

unsigned short DevHandle Handle previously returned by DosOpen 

Values for *PtrStatu$: 

Value Meaning 

0x01 Waiting for CTS 

0x02 Waiting for DSR 

0x04 Waiting for DCD 

0x08 Waiting because XOFF received 

Ox 10 Waiting because XOFF transmitted 

0x20 Waiting because break being transmitted 

0x40 Waiting to transmit immediately 

0x80 Waiting for DSR to be turned on 


Category Olh, .’ 

Function 651k ♦ purpose 

Get Line Status Returns status of data transmission on given serial device. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrTransStatus , 0L, 0x0065, 0x0001, 
DevHandle) 

Parameter Meaning 

unsigned char far *PtrTransStatus Pointer to variable with a 

combination of the values shown 
below 

unsigned short DevHandle Handle previously returned by 

DosOpen 


Values for *PtrTransStatus: 

Value Meaning 

0x01 Write request packets in progress or queued 
0x02 Data in device-driver transmit queue 
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Category Olh, 
Function 66ii: 
Get Modem 
Output 


Category Olh, 
Function 67h: 

Get Modem Input: 


0x04 Transmit hardware currently transmitting 

0x08 Character waiting for immediate transmission 

Ox 10 Waiting to automatically transmit XOFF 

0x20 Waiting to automatically transmit XON 


♦ Purpose 

Returns output control line statuses for a serial device. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (PtrCtrlSignals, 0L, 0x0066, 0x0001, 
DevHandle) 

Parameter Meaning 

unsigned char far *PtrCtrlSignals Pointer to variable with a 

combination of the values shown 

below 

unsigned short DevHandle Handle previously returned by 

DosOpen 


Values for *PtrCtrlSignals: 

Value Meaning 
0x01 DTR on 
0x02 RTS on 


♦ Purpose 

Returns input control line statuses for a serial device. 

❖ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrCtrlSignals , 0L, 0x0067, 0x0001, 
DevHandle) 


Parameter Meaning 

unsigned char far *PtrCtrlSignals Pointer to variable with a 

combination of the values shown 
below 
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unsigned short DevHandle Handle previously returned by 

DosOpen 

Values for *PtrCtrISignal$: 


Value 

Meaning 

0x10 

CTSon 

0x20 

DSR on 

0x40 

Ring indicator (RI) on 

0x80 

DCD on 


Category flits, 
Function 68h: 
Get inqueue 
Count 


♦ Purpose 

Returns number of characters in device-driver receive queue. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (PtrReceiveQue, OL, 0x0068 0x0001 
DevHandle) 

Parameter Meaning 

unsigned int far *PtrReceiveQue Pointer to structure described 

below 

unsigned short DevHandle Handle previously returned by 

DosOpen 

♦ Structures 

struct ReceiveQue 

{ 

unsigned int Chars; /* Number of characters in queue. */ 

unsigned int Queue; /* Size in bytes of queue. */ 


Category Olh, 

Function 69h° ♦ Purpose 

Get Outque Count Returns the number of characters in the device-driver transmit queue. 
♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrTransmitQue , 0L, 0x0069, 0x0001, 
DevHandle) 
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Parameter Meaning 

unsigned int far *PtrTransmitQue Pointer to structure described 

below 

unsigned short DevHandle Handle previously returned by 

DosOpen 

♦ Structures 

struct TransmitQue 

{ 

unsigned int Chars; 
unsigned int Queue 
}; 

Category 01h 5 

Function 6Dh“ « Purpose 
Get Comm Error Returns and clears the communication error word. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (PtrCommErr, OL, 0x006D, 0x0001, 
DevHandle) 

Parameter Meaning 

unsigned int far *PtrCommErr Pointer to variable to receive 

communications status of device, 
with a combination of the values 
shown below 

unsigned short DevHandle Handle previously returned by 

DosOpen 

Values for *PtrCommErr : 

Value Meaning 

0x0001 Receive character overrun: no room to read character from 
receive hardware 

0x0002 Receive hardware overrun: character received before 
preceding character read 

0x0004 Parity error 

0x0008 Framing error 


/* Number of characters in queue. *1 
/* Size in bytes of queue. */ 



548 


Programmer’s 
Guide to OS/2 
appC 


Category 01 h, 
Function 72h: 
Get Comm Event 


Category Olh, 
Function 73h: 
Get DCS info 


♦ Purpose 

Returns flags from event word as described below. 

* Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrEvent , OL, 0x0072, 0x0001, DevHandle) 

Parameter Meaning 

unsigned int far *PtrEvent Pointer to variable to receive event flags, 

with a combination of the values shown 
below 

unsigned short DevHandle Handle previously returned by DosOpen 
Values for *PtrEvent: 


Value 

Meaning 

0x0001 

Character has been read and placed in receive queue 

0x0004 

Last character in transmit queue has been sent 

0x0008 

CTS has changed state 

0x0010 

DSR has changed state 

0x0020 

DCD has changed state 

0x0040 

Break detected 

0x0080 

Parity, framing, or overrun error 

0x0100 

Trailing edge of ring indicator (RI) detected 


♦ Purpose 

Returns information from device-control block. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl {PtrDCB, 0L, 0x0073, 0x0001, DevHandle) 

Parameter Meaning 

unsigned int far *PtrDCB Pointer to structure described below 

unsigned short DevHandle Handle previously returned by DosOpen 
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Structures 

struct DCB 

{ 

unsigned int WriteTimeout; /* Timeout in hundredths of second, minus 1. */ 
unsigned int ReadTimeOut; /* Timeout in hundredths of second, minus 1. */ 
unsigned char Flagsl; /* Control and handshaking modes, as below. */ 
unsigned char Flags2; /* Flow control modes, as below. */ 

unsigned char Flags3; /* Timeout processing, as below. */ 

unsigned char ErrorReplacementChar; /* Error replacement character. */ 
unsigned char BreakReplacementChar; / * Break replacement character. */ 
unsigned char XONChar; /* XON character. */ 

unsigned char XOFFChar; /* XOFF character. *1 

}i 

Values for Flagsl, some of which may be combined: 

Value Meaning 

0x00 Disable DTR control 

0x01 Enable DTR control 

0x02 Enable DTR input handshaking mode; DTR controlled 
through device driver 

0x08 Enable CTS output handshaking 

0x10 Enable DSR output handshaking 

0x20 Enable DCD output handshaking 

0x40 Enable DSR input sensitivity, so input is lost if DSR is clear 
Values for Flags2, some of which may be combined: 

Value Meaning 

0x01 Enable automatic XON/XOFF transmit flow control 

0x02 Enable automatic XON/XOFF receive flow control 

0x04 Enable error replacement character 

0x08 Enable null stripping 

0x10 Enable break replacement character 

0x40 Enable RTS control mode 

0x80 Enable RTS input handshaking mode; RTS controlled through 
device driver 

OxCO Enable toggling on transmit mode; RTS will be on when there 
is data to transmit 
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Values for FlagsS, which may combine these values: 


Value Meaning 

0x01 Enable write infinite timeout 

0x02 Enable normal read timeout 

0x04 Enable wait-for-something read timeout 

0x06 Enable no-wait read timeout 


Category 03: Screen/Pointer-Draw Control 


Category Q3h, 
Function 72h: 
Get Ptr Draw 
Address 


* Purpose 

Returns entry-point address of pointer-draw function. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrFunctionlnfo , OL, 0x0072, 0x0003, 
DevHandle) 


Parameter Meaning 

unsigned char far *PtrFunctionInfo Pointer to structure described 

below 

unsigned short DevHandle Handle previously returned by 

DosOpen 

♦ Structures 

struct Functionlnfo 

{ 

unsigned int ReturnCode; /* Return code of pointer-draw function. */ 

PFN Draw; /* with ’typedef int (pascal far *PFN)();’. */ 

unsigned short Data Selector; /* Data-segment selector of function */ 

} 


Category 04: Keyboard Control 


Category 04h, 

Function §0h: ♦ purpose 

Set Irani Table Activates a new keyboard translation table. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrTransTable, 0x0050, 0x0004, 
DevHandle) 
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Category 04h, 
Function 51h: 
Set input Mode 


Category 04h, 
Function 52h: 
Set Interim Flag 


Parameter 

unsigned char far *PtrTransTable 
unsigned short DevHandle 


Meaning 

Pointer to keyboard translation 
table 

Handle previously returned by 
DosOpen 


♦ Purpose 

Governs processing of Control-C, Control-Break, Control-S, Control-P, 
Scroll Lock, and PrtSc keys. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrlnputMode , 0x0051,0x0004, 
DevHandle) 


Parameter 

unsigned char far *PtrlnputMode 

unsigned short DevHandle 


Meaning 

Pointer to variable with 
combination of the values shown 
below 

Handle previously returned by 
DosOpen 


Values for 

* PtrlnputMode : 

Value 

Meaning 

0x00 

Cooked input mode; shift reporting disabled 

0x01 

Shift reporting enabled 

0x80 

Raw input mode 


♦ Purpose 

Sets the interim character flags for a screen group. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrFlags , 0x0052, 0x0004, DevHandle) 

Parameter Meaning 

unsigned char far *PtrFlags Pointer to flags, with either or both of 

the values shown below 
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Category 04h, 
Function 53h: 
Set Shift State 


unsigned short DevHandle Handle previously returned by DosOpen 
Values for *PtrFlags: 

Value Meaning 

0x0020 Conversion requested 
0x0080 Interim character flag on 


♦ Purpose 

Sets the states of shift keys. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrShiftState, 0x0053, 0x0004, 
DevHandle) 

Parameter Meaning 

unsigned char far *PtrShiftState Pointer to structure described 

below 

unsigned short DevHandle Handle previously returned by 

DosOpen 

♦ Structures 

struct ShiftState 

{ 

unsigned int State; /* Shift states, as shown below. */ 

unsigned char NLS; /* NLS-dependent states; 0 in U.S. *1 

}; 


Values for State: 

Value 

Meaning 

0x0000 

Shift keys up 

0x0001 

Right Shift key down 

0x0002 

Left Shift key down 

0x0004 

Either Control key down 

0x0008 

Either Alt key down 

0x0010 

Scroll Lock turned on 
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Category 04h, 
Function 54h: 
Set Typamatic 
Rate 


Category 04h, 
Function 55h: 
Set Foreground 
Screen Group 


0x0020 

Num Lock turned on 

0x0040 

Caps Lock turned on 

0x0080 

Insert turned on 

0x0100 

Left Control key down 

0x0200 

Left Alt key down 

0x0400 

Right Control key down 

0x0800 

Right Alt key down 

0x1000 

Scroll Lock key down 

0x2000 

Num Lock key down 

0x4000 

Caps Lock key down 

0x8000 

Sys Req key down 


♦ Purpose 

Sets the keyboard repeat rate and delay time. 

❖ Catling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrRateDelay, 0x0054, 0x0004, 


DevHandle) 

Parameter 

unsigned int far *PtrRateDelay 
unsigned short DevHandle 

♦ Structures 

struct RateDelay 

{ 

unsigned int Delay; 
unsigned int Rate; 

}; 


Meaning 

Pointer to structure described below 

Handle previously returned by 
DosOpen 


/* Delay in milliseconds. */ 

/* Rate in characters per second. */ 


♦ Purpose 

Switches a screen group to the foreground, for use by the session manager. 
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♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrScreenGroup, 0x0055, 0x0004, 
DevHandle) 

Parameter Meaning 

unsigned int far *PtrScreen Group Pointer to structure described 

below 

unsigned short DevHandle Handle previously returned by 

DosOpen 

♦ Structures 

struct ScreenGroup 

{ 

unsigned int ScreenGrp; /* New screen group identifier, 0-15. */ 

unsigned int Terminate; /* 0x0000 = switch; OxFFFF = terminate. */ 

}; 


Category 04h, 

Function 56h: + Purpose 

Set Session Allows the session manager to set a list of hotkeys. 

Manager Hotkey , MBng Prol0c0 | 

unsigned int pascal far DosDevlOCtl (0L, PtrHotKey, 0x0056, 0x0004, 
DevHandle) 


Parameter 

unsigned char far *PtrHotKey 
unsigned short DevHandle 

❖ Structures 

struct HotKey 

{ 

unsigned int HotKey; 
unsigned char ScanCodeMake; 

unsigned char ScanCodeBreak; 

unsigned int HotKeylD; 

}; 


Meaning 

Pointer to structure described below 

Handle previously returned by 
DosOpen 


/* Shift settings as described below. */ 

/* Scan code on make, causes detect on */ 
/* make if given. */ 

/* Scan code on break, causes detect on */ 
/* break if given. */ 

/* Session-manager hotkey identifier, */ 

/*from0to15. */ 
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Category 04h, 
Function 57h: 
Set Focus 


Category Q4h, 
Function 71h: 
Get Input Mode 


Values for BotKey: 


Value 

Meaning 

0x0001 

Right Shift key down 

0x0002 

Left Shift key down 

0x0100 

Left Control key down 

0x0200 

Left Alt key down 

0x0400 

Right Control key down 

0x0800 

Right Alt key down 

0x1000 

Scroll Lock key down 

0x2000 

Num Lock key down 

0x4000 

Caps Lock key down 

0x8000 

Sys Req key down 


♦ Purpose 

Gives a logical keyboard the focus. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrKbd, 0x0057, 0x0004, DevHandle) 

Parameter Meaning 

unsigned short far *PtrKbd Pointer to logical keyboard handle 

previously returned by KbdOpen 

unsigned short DevHandle Handle previously returned by DosOpen 


♦ Purpose 

Returns information on treatment of keys Control-C 5 Control-Break, 
Control-S, Control-P, Scroll Lock, and PrtSc. 

* Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrlnputMode , 0L, 0x0071,0x0004, 
DevHandle) 
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Category 04h, 
Function 72h: 
Get Interim Flag 


Category 04h, 
Function 73h: 
Get Shift State 


Parameter 

unsigned char far *PtrInputMode 

unsigned short DevHandle 


Meaning 

Pointer to variable with possible 
values 0 = cooked mode and 
1 = raw mode 

Handle previously returned by 
DosOpen 


0 PtrFlags , OL, 0x0072, 0x0004, DevHandle) 


♦ Purpose 

Returns interim character flags. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl 

Parameter 

unsigned char far *PtrFlag$ 

unsigned short DevHandle 


Meaning 

Pointer to variable to receive interim 
flags, with possible values 
0x20 = conversion requested and 
0x80 = interim console flag is on 

Handle previously returned by DosOpen 


♦ Purpose 

Returns states of shift keys in current screen group. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (PtrShiftState, 0L, 0x0073, 0x0004, 
DevHandle) 

Parameter Meaning 

unsigned char far *PtrShiftState Pointer to structure described 

below 

unsigned short DevHandle Handle previously returned by 

DosOpen 

♦ Structures 

struct ShiftState 

{ 

unsigned int Stat; /* Shift states, as given below. */ 



Category 04h, 
Function 74h: 
Bead Character 
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unsigned char NLS; /* States of NLS keys. */ 

}; 


Values for State: 

Value 

Meaning 

0x0001 

Right Shift key down 

0x0002 

Left Shift key down 

0x0004 

Either Control key down 

0x0008 

Either Alt key down 

0x0010 

Scroll Lock turned on 

0x0020 

Num Lock turned on 

0x0040 

Caps Lock turned on 

0x0080 

Insert turned on 

0x0100 

Left Control key down 

0x0200 

Left Alt key down 

0x0400 

Right Control key down 

0x0800 

Right Alt key down 

0x1000 

Scroll Lock key down 

0x2000 

Num Lock key down 

0x4000 

Caps Lock key down 

0x8000 

Sys Req key down 


♦ Purpose 

Returns one or more characters from the keyboard input buffer for the cur¬ 
rent screen group. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (iPtrBuffer , PtrRecords, 0x0074, 0x0004, 

Dev Handle) 

Parameter Meaning 

KBBKEYINFO far *PtrBuffer Pointer to buffer to receive copy or 

copies of structure described below 
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unsigned int far *PtrRecord$ 
unsigned short DevHandle 


Pointer to variable containing 
number of records to be read 

Handle previously returned by 
DosOpen 


4 Structures 

typedef struct _KBDKEYINFO 


{ 


unsigned char chChar; 

/* Character translated from chScan. 

*/ 

unsigned char chScan; 

/* Keyboard scan code. 

*/ 

unsigned char fbStatus; 

/* Scan code status, as below. 

*/ 

unsigned char bNIsShift; 

/* Reserved, must be zero. 

*/ 

unsigned int fsState; 

/* States of shift keys, as below. 

*/ 

unsigned long time; 

/* Time stamp of keystroke in 

*/ 

} 

KBDKEYINFO; 

/* milliseconds. 

*/ 


Values for fbStatus: 


Value Meaning 

0x0001 Shift key received; used in raw mode, shift report on 
0x0020 Conversion requested 

0x0040 Final character received 

0x0080 Interim character received 

Values for fsState: 

Value Meaning 

0x0000 Shift keys up * 

0x0001 Right Shift key down 

0x0002 Left Shift key down 

0x0004 Either Control key down 

0x0008 Either Alt key down 

0x0010 Scroll Lock turned on 

0x0020 Num Lock turned on 

0x0040 Caps Lock turned on 

0x0080 Insert turned on 

0x0100 Left Control key down 
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Category 04h, 
Function 75ti: 
Peek Character 


0x0200 

Left Alt key down 

0x0400 

Right Control key down 

0x0800 

Right Alt key down 

0x1000 

Scroll Lock key down 

0x2000 

Num Lock key down 

0x4000 

Caps Lock key down 

0x8000 

Sys Req key down 


♦ Purpose 

Returns one or more characters from the keyboard input buffer for the cur¬ 
rent screen group without removing them from the buffer. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl {PtrBuffer, PtrStatus , 0x0075, 0x0004, 
DevHandle ) 


Parameter 

KBDKEYINFO far *PtrBuffer 
unsigned int far *PtrStatus 

unsigned short DevHandle 


Meaning 

Pointer to structure described below 

Pointer to variable to receive 
keyboard status; may combine the 
values shown below 

Handle previously returned by 
DosOpen 


Values for *PtrStatus : 


Value 

Meaning 

0x0000 

No character available 

0x0001 

Character record retrieved 

0x8000 

Raw input mode 


♦ Structures 

typedef struct _KBDKEYINFO 

{ 

unsigned char chChar; 
unsigned char chScan; 
unsigned char fbStatus; 


/* Character translated from chScan. */ 
/* Keyboard scan code. */ 

/* Scan code status, as below. */ 
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unsigned char bNIsShift; 

/* Reserved, must be zero. 

*/ 

unsigned int fsState; 

/* States of shift keys, as below. 

*/ 

unsigned long time; 

/* Time stamp of keystroke in 

*/ 

} 

/* milliseconds. 

*/ 

KBDKEYINFO; 




Values for fbStatus: 

Value Meaning 

0x0001 Shift key received; used in raw mode, shift report on 
0x0020 Conversion requested 

0x0040 Final character received 

0x0080 Interim character received 

Values for fsState: 

Value Meaning 

0x0000 Shift keys up 

0x0001 Right Shift key down 

0x0002 Left Shift key down 

0x0004 Either Control key down 
0x0008 Either Alt key down 

0x0010 Scroll Lock turned on 

0x0020 Num Lock turned on 

0x0040 Caps Lock turned on 

0x0080 Insert turned on 

0x0100 Left Control key down 

0x0200 Left Alt key down 

0x0400 Right Control key down 

0x0800 Right Alt key down 

0x1000 Scroll Lock key down 

0x2000 Num Lock key down 

0x4000 Caps Lock key down 

0x8000 Sys Req key down 




Input/Output Control Functions 


Category 04h, 
Function 76h: 
Get Session 
Manager Hotkey 


Hi 


4 Purpose 

Returns number of hotkeys currently defined, or their values, 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (PtrHotKeyBuf, PtrHotKeys, 0x0076, 
0x0004, Dev Handle) 

Parameter Meaning 


unsigned char far *PtrHotKeyBuf 


unsigned int far *PtrHotKeys 


unsigned short DevHandle 

♦ Structures 

struct HotKeyBuf 

{ 

unsigned int HotKey; 
unsigned char ScanCodeMake; 

unsigned char ScanCodeBreak; 

unsigned int HotKeylD; 

}; 

Values for HotKey: 


Pointer to buffer to receive copy 
or copies of structure described 
below 

Pointer to variable specifying 
number of hotkey structures to 
return: value 0 = maximum 
number supported by keyboard 
device driver; value 1 = number 
currently used 

Handle previously returned by 
DosOpen 


/* Shift settings as described below. */ 

/* Scan code on make, causes detect on */ 
/* make if given. *1 

I* Scan code on break, causes detect on */ 
/* break if given. */ 

/* Session-manager hotkey identifier, */ 

/*from0to15. */ 


Value Meaning 

0x0001 Right Shift key down 

0x0002 Left Shift key down 

0x0100 Left Control key down 

0x0200 Left Alt key down 

0x0400 Right Control key down 
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0x0800 

Right Alt key down 

0x1000 

Scroll Lock key down 

0x2000 

Num Lock key down 

0x4000 

Caps Lock key down 

0x8000 

Sys Req key down 


Category 04h, 
Function 77ii: 
Get Keyboard 
Type 


❖ Purpose 

Returns type of keyboard. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (PtrType, OL, 0x0077, 0x0004, DevHandle) 


Parameter Meaning 


unsigned char far *PtrType Pointer to structure described below 
unsigned short DevHandle Handle previously returned by DosOpen 


Structures 

struct Type 
{ 

unsigned int Type; 



/* Type: 0 = PC AT 1 = PS/2, 

*/ 


/* 2-7 = various Japanese. 

*/ 

unsigned int Reservedl; 

/* Reserved, set to zero. 

*/ 

unsigned int Reserved2; 

/* Reserved, set to zero. 

*/ 


}; 


Category 05h: Printer Control 


Purpose 

Sets line- and column-spacing control for a printer. 

Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrFrameCtl , PtrCommand, 0x0042, 
0x0005, DevHandle) 


Category 05h, 
Function 42b: 
Set Frame 
Contro! 


Parameter Meaning 

unsigned char far *PtrFrameCtl Pointer to structure described 

below 




Category 05h, 
Function 44h: 

Set infinite Retry 


Category 05h, 
Function 46h: 
Initialize Printer 


Input/Output Control Functions 
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unsigned char far *PtrCommand Pointer to reserved value zero 

unsigned short DevHandle Handle previously returned by 

DosOpen 

♦ Structures 

struct FrameCtl 

{ 

unsigned char CharsPerLine; /* Either 80 or 132. */ 

unsigned char LinesPerlnch; /* Either 6 or 8. */ 

}; 


♦ Purpose 

Sets infinite retry for a printer. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl {PtrRetry, PtrCommand , 0x0044, 0x0005, 
DevHandle) 


Parameter 

unsigned char far *PtrRetry 

unsigned char far * PtrCommand 
unsigned short DevHandle 


Meaning 

Pointer to variable: 

value 0 = infinite retry disabled; 

value 1 = infinite retry enabled 

Pointer to reserved value zero 

Handle previously returned by 
DosOpen 


♦ Purpose 

Initializes a printer. 

* Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrCommand , 0x0046, 0x0005, 
DevHandle) 

Parameter Meaning 

unsigned char far * PtrCommand Pointer to reserved value zero 

unsigned short DevHandle Handle previously returned by 

DosOpen 
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Category 05lt, 
Function 62h: 
Get Frame 
Control 


* Purpose 

Returns line- and column-spacing information for a printer. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrFrameCtl, PtrCommand, 0x0062, 
0x0005, DevHandle) 


Parameter 

unsigned char far *PtrFrameCtl 

unsigned char far ^PtrCommand 
unsigned short DevHandle 


* Structures 

struct FrameCtl 

{ 

unsigned char CharsPerLine; 
unsigned char LinesPerlnch; 
}; 


Meaning 

Pointer to structure described 
below 

Pointer to reserved value zero 

Handle previously returned by 
DosOpen 


/* Either 80 or 132. 
/* Either 6 or 8. 


Category 05h, 
Function 64h: 

Get Infinite Retry 


Parameter Meaning 

unsigned char far *PtrRetry Pointer to variable: 

value 0 = infinite retry disabled; 
value 1 = infinite retry enabled 

unsigned char far *PtrCommand Pointer to reserved value zero 

unsigned short DevHandle Handle previously returned by 

DosOpen 


* Purpose 

Returns infinite retry status of a printer. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl {PtrRetry, PtrCommand, 0x0064, 0x0005, 
DevHandle ) 
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Category 05h, 
Function 66h: 
Get Printer 
Status 


♦ Purpose 

Returns information about printer operation. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (PtrStatus, PtrCommand, 0x0066, 0x0005, 
DevHandle) 


Parameter 

unsigned char far *PtrStatus 

unsigned char far *PtrCommand 
unsigned short DevHandle 


Meaning 

Pointer to variable to receive 
printer status, which may be a 
combination of the values shown 
below 

Pointer to reserved value zero 

Handle previously returned by 
DosOpen 


Values for *PtrStatus : 


¥aloe 

Meaning 

0x0001 

Timeout occured 

0x0008 

I/O error occured 

0x0010 

Printer selected 

0x0020 

Printer out of paper 

0x0040 

Printer acknowledged 

0x0080 

Printer not busy 


Category 07: Mouse Control 


Category 07h, 
Function 50h: 
Allow Pointer 
Draw 


♦ Purpose 

Notifies mouse device driver of a completed screen group switch, so that the 
mouse pointer can be redrawn. 


♦ Celling Protocol 

unsigned int pascal far DosDevlOCtl (0L, 0L, 0x0050, 0x0007, DevHandle) 


Parameter Meaning 

unsigned short DevHandle Handle previously returned by DosOpen 





566 


Programmer’s 
Guide to OS/2 
APP C 


Category 07h, 
Function 51h: 
Update Display 
Mode 


Category 07h, 
Function 52h: 
Screen Switch 


* Purpose 

Notifies mouse driver of change in mode of display. 

* Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrMode, 0x0051,0x0007, DevHandle) 

Parameter Meaning 

VIOMODEINFO far *PtrMode Pointer to structure described below 

unsigned short DevHandle Handle previously returned by 

DosOpen 

* Structures 


typedef struct _VIOMODEINFO 
{ 


unsigned int cb; 

/* Length in bytes of structure. 

*/ 

unsigned int fbType; 

/* Adapter and mode types, as below. 

*/ 

unsigned char color; 

/* Number of colors as power of 2. 

*/ 

unsigned int col; 

/* Number of text columns. 

*/ 

unsigned int row; 

/* Number of text rows. 

*/ 

unsigned int hres; 

/* Number of pixels across screen. 

*/ 

unsigned int vres; 

/* Number of pixels down screen. 

*/ 

unsigned char fmt_ID; 

/* Reserved, set to zero. 

*/ 

unsigned char attrib; 

} 

VIOMODEINFO; 

/* Reserved, set to zero. 

*/ 


♦ Purpose 

Notifies the mouse device driver of an impending screen switch and disal¬ 
lows further pointer drawing. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrNotify, 0x0052, 0x0007, DevHandle) 

Parameter Meaning 

unsigned char far *PtrNotify Pointer to structure described below 

unsigned short DevHandle Handle previously returned by 

DosOpen 
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Category 07h, 
Function 53fi: 

Set Scale Factors 


Category 07h, 
Function 54h: 
Set Event Mask 


♦ Structures 

struct Notify 

unsigned int Number; /* Number of screen group to notify, 

unsigned int Terminate; /* Value OxFFFF = screen group is 

/* terminating; value 0x0000 = screen 
y /* group is receiving control. 


* Purpose 

Sets scaling factors—mickeys per pixel or mickeys per character tor 
mouse. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrFactors , 0x0053, 0x0007, 

DevHandle) 


Parameter 

SCALEFACT far *PtrFactors 
unsigned short DevHandle 

♦ Structures 

typedef struct _SCALEFACT 

{ 

unsigned int rowScale; 
unsigned int colScale; 

} 

SCALEFACT; 


Meaning 

Pointer to structure described below 

Handle previously returned by 
DosOpen 

/* Values from 0 to 32,767; */ 

/* Horizontal scaling factor. */ 

/* Vertical scaling factor. */ 


♦ Purpose 

Sets the event mask for the mouse. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrEvent, 0x0054, 0x0007, DevHandle) 


Parameter Meaning 

unsigned int far *PtrEvent Pointer to variable containing event 

mask, which may combine the values 
shown below 
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Category 07h, 
Function 55h: 
Set Hotkey 
Button 


unsigned short DevHandle Handle previously returned by DosOpen 
Values for *PtrEvent : 


Value 

Meaning 

0x0001 

Motion with no buttons pressed 

0x0002 

Motion with button 1 pressed 

0x0004 

Button 1 pressed 

0x0008 

Motion with button 2 pressed 

0x0010 

Button 2 pressed 

0x0020 

Motion with button 3 pressed 

0x0040 

Button 3 pressed 


♦ Purpose 

Sets mouse buttons to affect system hotkey function. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrHotKey , 0x0055, 0x0007 


DevHandle) 

Parameter 

unsigned int far *PirHotKey 

unsigned short DevHandle 
Values for PtrHotKey : 

Valye Meaning 

0x0001 No hotkey desired 

0x0002 Use button 1 

0x0004 Use button 2 

0x0008 Use button 3 


Meaning 

Pointer to variable specifying button, 
which may combine the values shown 
below 

Handle previously returned by DosOpen 
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Category 07h, 
Function §6h: 
Set Pointer 
Shape 


Category 07h, 
Function 57h: 
Draw Pointer 


$ Purpose 

Sets the shape of the pointer. 

* Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrBuffer , PtrShape , 0x0056, 0x0007, 
DevHandle) 


Parameter 


Meaning 


unsigned char far *PtrBuffer Pointer to buffer containing pointer 

image (AND data then OR data for 
one display plane) 

PTRSHAPE far *PtrShape Pointer to structure described below 

unsigned short DevHandle Handle previously returned by 

DosOpen 


* Structures 

typedef struct _PTRSHAPE 


{ 

unsigned int cb; 


unsigned int col; 
unsigned int row; 
unsigned int colHot; 
unsigned int rowHot; 
} 

PTRSHAPE; 


/* Length in bytes of pointer shape buffer. */ 
/* For text mode, ’cb’ should be set to 4; */ 

/* for graphics mode, ’cb’ should be set to: */ 
/* row x col x bits-per-pixel x 2/8. */ 

/* Column width of image. */ 

/* Row height of image. */ 

/* Column offset to pointer hot spot. */ 

/* Row offset to pointer hot spot. */ 


* Purpose 

Removes an exclusion rectangle, redrawing the mouse pointer if the mouse 
pointer was within the rectangle. 

* Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, 0L, 0x0057, 0x0007, DevHandle) 

Parameter Meaning 

unsigned short DevHandle Handle previously returned by DosOpen 
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Category 07h, 
Function 58h: 
Remove Pointer 


Category Dili, 
Function 59h: 
Set Pointer 
Position 


♦ Purpose 

Specifies an exclusion rectangle within which the mouse pointer will not 
be drawn. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrBuffer, 0x0058, 0x0007, DevHandle) 


Parameter 

NOPTRRECT far *PtrBuffer 
unsigned short DevHandle 

♦ Structures 

typedef struct _NOPTRRECT 

{ 

unsigned int row; 
unsigned int col; 
unsigned int cRow; 
unsigned int cCol; 

} 

NOPTRRECT; 


Meaning 

Pointer to structure described below 

Handle previously returned by 
DosOpen 


/* Starting X-coordinate. */ 

/* Starting Y-coordinate. */ 

/* Height of exclusion rectangle. */ 

/* Width of exclusion rectangle. */ 


♦ Purpose 

Positions the mouse pointer. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrPosition , 0x0059, 0x0007, 
DevHandle) 

Parameter Meaning 

PTRLOC far *PtrPosition Pointer to structure described below 

unsigned short DevHandle Handle previously returned by DosOpen 

♦ Structures 

typedef struct _PTRLOC 

{ 

unsigned int row; /* X-coordinate. */ 



Category 07h, 
Function 5 Ah: 
Set Protested 
Mode Draw 
Address 


Category 07h, 
Function 5Bh: 
Set Real Mode 
Draw Address 


Input/Output Control Functions 
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unsigned int col; /* Y-coordinate. */ 

} 

PTRLOC; 


♦ Purpose 

Provides the mouse driver with the address of a protected mode pointer- 
draw function. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrFunction , 0x005A, 0x0007, 
DevHandle) 

Parameter Meaning 

unsigned char far *PtrFunction Pointer to structure described below 

unsigned short DevHandle Handle previously returned by 

DosOpen 

♦ Structures 

struct Function 


PFN Draw; 

/* Address of pointer-draw function 

*/ 


/* with ’typedef int (pascal far *PFN)();’. 

*1 

char far *DataSeg; 

/* Starting address of data segment 

*/ 

}; 

/* of pointer-draw function. 

*/ 


♦ Purpose 

Provides the mouse driver with the entry point of a real mode pointer-draw 
function, for use by the session manager. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrFunction, 0x005B, 0x0007, 
DevHandle) 

Parameter Meaning 

unsigned char far *PtrFunction Pointer to structure described below 

unsigned short DevHandle Handle previously returned by 

DosOpen 
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Category 07h, 
Function 5Ch: 

Set Mouse Status 


Category 07h, 
Function 60h: 

Get Button Count 


♦ Structures 


struct Function 



PFN Draw; 

/* Address of pointer-draw function 

*/ 


/* with ’typedefint (pascal far *PFN)();\ 

*/ 

char far *DataSeg; 

/* Starting address of data segment of 

*/ 

}; 

/* pointer-draw function. 

*/ 


♦ Purpose 

Sets certain mouse device-driver status flags. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrStatus, 0x005C, 0x0007, DevHandle) 

Parameter Meaning 

unsigned int far *PtrStatus Pointer to status flags variable, which 

may combine the values shown below 

unsigned short DevHandle Handle previously returned by DosOpen 
Values for *PtrStatus: 

Value Meaning 

0x0100 Interrupt-level pointer-draw routine not called 
0x0200 Mouse data returned in mickeys 


♦ Purpose 

Returns number of mouse buttons. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrCount , 0L, 0x0060, 0x0007, DevHandle) 

Parameter Meaning 

unsigned int far *PtrCount Pointer to variable to receive number of 

buttons 

unsigned short DevHandle Handle previously returned by DosOpen 
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Category Q7h, 
Function Sih: 

Get Mickey Count 


Category 071?, 
Function 62h: 

Get Mouse Status 


♦ Purpose 

Returns number of mickeys per centimeter of a mouse. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrMickeys , OL, 0x0061,0x0007, 
DevHandle) 

Parameter Meaning 

unsigned int far *PtrMickeys Pointer to variable to receive mickeys 

per centimeter, from 0 to 32,767 

unsigned short DevHandle Handle previously returned by 

DosOpen 


♦ Purpose 

Returns status flags for the mouse. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrStatus , 0L, 0x0062, 0x0007, DevHandle) 


Parameter Meaning 

unsigned int far *PtrStatus Pointer to variable to receive status flags, 

which may be any combination of the 
values shown below 

unsigned short DevHandle Handle previously returned by DosOpen 


Values for *PtrStatus: 


Valye 

Meaning 

0x0001 

Event queue busy with I/O 

0x0002 

Block read in progress 

0x0004 

Flush in progress 

0x0008 

Pointer-draw routine disabled 

0x0100 

Interrupt-level printer-draw routine not called 

0x0200 

Mouse data returned in mickeys 
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Category 07ti, 
Function 63h: 
Read Etch! 
Queue 


Parameter Meaning 

MOUEVENTINFO far *PtrEvent Pointer to structure described 

below 

unsigned int far *PtrWait Pointer to variable with the values 

shown below 

unsigned short DevHandle Handle previously returned by 

DosOpen 


♦ Purpose 

Reads the mouse event queue. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl {PtrEvent, PtrWait , 0x0063, 0x0007, 
DevHandle) 


Values for *PtrWait : 

Value Meaning 

0x0000 Return immediately in absence of an event 
0x0001 Wait for an event 

♦ Structures 

typedef struct _MOUEVENTINFO 

{ 

unsigned int fs; 
unsigned long Time; 
unsigned int row; 
unsigned int col; 

} 

MOUEVENTINFO: 

Values for fs: 


Value 

Meaning 

0x0001 

Motion with no buttons pressed 

0x0002 

Motion with button 1 pressed 

0x0004 

Button 1 pressed 

0x0008 

Motion with button 2 pressed 


/* Current event, as below. */ 

/* Time of event. */ 

/* Pointer X-coordinate. */ 

/* Pointer Y-coordinate. */ 
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Category 07h, 
Function 64h: 

Get Queue Status 


Category 07h, 
Function 65h: 
Get Event Mask 


0x0010 Button 2 pressed 

0x0020 Motion with button 3 pressed 

0x0040 Button 3 pressed 


♦ Purpose 

Returns number of elements in mouse event queue, as well as maximum 
possible number. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrStatus , 0L, 0x0064, 0x0007, DevHandle) 

Parameter Meaning 

MOUQUEINFO far *PtrStatu$ Pointer to structure described below 

unsigned short DevHandle Handle previously returned by 

DosOpen 

♦ Structures 

typedef struct _MOUQUEINFO 

{ 

unsigned int cEvents; /* Current number of events in queue. */ 

unsigned int cmaxEvents; /* Maximum number of events in queue. */ 

} 

MOUQUEINFO; 


❖ Purpose 

Returns current mouse event mask. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrEvents , 0L, 0x0065, 0x0007, DevHandle) 

Parameter Meaning 

unsigned int far *PtrEvents Pointer to variable to receive event mask, 

which may combine the values shown 
below 

unsigned short DevHandle Handle previously returned by DosOpen 
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Category 07h, 
Function S6h: 

Get Scale Factors 


Category 07h, 
Function 67h: 
Get Pointer 
Position 


Values for *PtrEvents : 


Value 

Meaning 

0x0001 

Motion with no buttons pressed 

0x0002 

Motion with button 1 pressed 

0x0004 

Button 1 pressed 

0x0008 

Motion with button 2 pressed 

0x0010 

Button 2 pressed 

0x0020 

Motion with button 3 pressed 

0x0040 

Button 3 pressed 


♦ Purpose 

Gets scaling factors—mickeys per pixel or mickeys per character—for 
mouse. 

♦ Calling Proloeol 

unsigned int pascal far DosDevlOCtl ( PtrFactors, OL, 0x0066, 0x0007, 

DevHandle) 


Parameter 

SCALEFACT far *PtrFactors 
unsigned short DevHandle 

♦ Structures 

typedef struct _SCALEFACT 

{ 

unsigned int rowScale; 
unsigned int colScale; 

} 

SCALEFACT; 


Meaning 

Pointer to structure described below 

Handle previously returned by 
DosOpen 

/* Values from 0 to 32,767: */ 

/* Horizontal scaling factor. */ 

/* Vertical scaling factor. */ 


♦ Purpose 

Returns current position of screen pointer. 
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♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrPosition , OL, 0x0067, 0x0007, 
DevHandle) 


Parameter Meaning 


PTRLOC far *PtrPosition Pointer to structure described below 
unsigned short DevHandle Handle previously returned by DosOpen 


♦ Structures 

typedef struct _PTRLOC 

{ 

unsigned int row; /* X-coordinate. */ 

unsigned int col; /* Y-coordinate. */ 

} 

PTRLOC; 


Category 07h, 
Function 68h: 
Get Pointer 
Shape 


♦ Purpose 

Returns current mouse pointer shape. A nonzero return value may indicate 
that the input buffer is of inadequate size. 

* Calling Protocol 

unsigned int pascal far DosDevlOCtl (PtrBuffer, PtrShape , 0x0068, 0x0007, 
DevHandle) 


Parameter 

unsigned char far *PtrBuffer 


PTRSHAPE far *PtrShape 


Meaning 

Pointer to buffer containing pointer 
image (AND data then OR data for 
one display plane) 

Pointer to structure described below 


unsigned short DevHandle Handle previously returned by 

DosOpen 


♦ Structures 

typedef struct _PTRSHAPE 

{ 


unsigned int cb; 

/* Length in bytes of pointer shape buffer. 

*/ 


/* For text mode, ’cb’ should be set to 4; 

*/ 


/* for graphics mode, ’cb’ should be set to: 

*/ 


/* row x col x bits-per-pixel x 2/8. 

*/ 
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unsigned int col; /* Column width of image. */ 

unsigned int row; /* Row height of image. */ 

unsigned int colHot; /* Column offset to pointer hot spot. */ 

unsigned int rowHot; /* Row offset to pointer hot spot. */ 

} 

PTRSHAPE; 


♦ Purpose 

Returns mouse button combination acting as system hotkey. 

❖ Calling Protocol 

unsigned int pascal far DosDevlOCtl (PtrHotKey, OL, 0x0069, 0x0007, 
DevHandle ) 

Parameter Meaning 

unsigned int far *PtrHotKey Pointer to variable to receive button, 

which may combine the values shown 
below 

unsigned short DevHandle Handle previously returned by 

DosOpen 

Values for *PtrHotKey : 

Value Meaning 

0x0001 No hotkey desired 

0x0002 Use button 1 

0x0004 Use button 2 

0x0008 Use button 3 


Category 08: Disk/Diskette Control 


Category 08h, 

Function OQh: 

Lock Drive 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrCommand, 0x0000, 0x0008, 
DevHandle) 


* Purpose 

Prevents other processes from accessing files on a drive. Caller must have 
at least one file open there. 


Category 07h, 
Function 69h: 
Get Hotkey 
Button 
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Parameter 

Meaning 


unsigned char far *PtrCommand 

Pointer to reserved value zero 


unsigned short DevHandle 

Handle previously returned by 
DosOpen 

Category 08h, 
Function Olh: 
Unlock Drive 

♦ Purpose 

Makes the files on a drive accessible to other processes. 


❖ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrCommand, 0x0001,0x0008, 
DevHandle) 


Parameter 

Meaning 


unsigned char far *PtrCommcmd 

Pointer to reserved value zero 


unsigned short DevHandle 

Handle previously returned by 
DosOpen 

Category 08h, 
Function 02h: 
Redetermine 
Media 

♦ Purpose 

Redetermines medium inserted in a drive after update of volume ID infor¬ 
mation. The volume should be locked. 


♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrCommand, 0x0002, 0x0008, 
DevHandle) 


Parameter 

Meaning 


unsigned char far *PtrCommand 

Pointer to reserved value zero 


unsigned short DevHandle 

Handle previously returned by 
DosOpen 

Category 08h, 
Function 03h: 

Set Logical Map 

* Purpose 

Sets the logical drive map for a drive. 
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♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (iPtrDrive , PtrCommand , 0x0003, 0x0008, 
DevHandle) 

Parameter Meaning 

unsigned char far *PtrDrive Pointer to variable containing 

logical drive number (beginning 
with 1 for drive Z): returns logical 
drive currently mapped to the drive 
on which the current file handle is 
open; returns zero if only one 
logical drive is mapped to the 
physical drive 

unsigned char far *PtrCommand Pointer to reserved value zero 

unsigned short DevHandle Handle previously returned by 

DosOpen 


Category 08h, 

Function 20h: ♦ Purpose 

Block Removable Finds if a drive is removable. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (PtrNonRemovable, PtrCommand 0x0020, 
0x0008, DevHandle) 


Parameter Meaning 

unsigned char far *PtrNonRemovable Pointer to variable with 


unsigned char far *PtrCommand 
unsigned short DevHandle 


values 0 = removable drive, 
1 = nonremovable 

Pointer to reserved value 0 

Handle previously returned 
by DosOpen 


Category QBh, 

Function 211k ♦ purpose 

Get Logical Map Returns the logical mapping of a drive. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrDrive , PtrCommand, 0x0021,0x0008, 
DevHandle) 
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Category 08h, 
Function 43h: 
Set Device 
Parameters 


Parameter Meaning 

unsigned char far *PtrDrive Pointer to variable to receive logical 

drive number (beginning with 1 for 
drive A); returns zero if only one 
logical drive is mapped to the 
physical drive 

unsigned char far ^PtrCornmand Pointer to reserved value zero 

unsigned short DevHandle Handle previously returned by 

DosOpen 


♦ Purpose 

Sets block device parameters. Maintains two BIOS parameter blocks: one 
the default for the device, and one according to the removable medium cur¬ 
rently in use. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrBPB , PtrCornmand, 0x0043, 0x0008, 
DevHandle ) 

Parameter Meaning 

unsigned char far *PtrBPB Pointer to structure described 

below 

unsigned char far *PtrCommand Pointer to variable containing one 

of the values shown 

unsigned short DevHandle Handle previously returned by 

DosOpen below 


Values for * PtrCornmand : 

Value Meaning 

0x00 Builds BIOS parameter block according to medium now 
inserted in drive 

0x01 Change the default BPB for the physical device 
0x02 Change the BPB for the medium as specified 

♦ Structures 

struct BPB 

{ 

unsigned int BytesPerSector; /* Bytes per sector. */ 
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Category QBh, 
Function 44h: 
Write Track 


unsigned char SectorsPerCluster; 

/* Sectors per cluster. 

*/ 

unsigned int ReservedSectors; 

/* Reserved sectors. 

*/ 

unsigned char FATs; 

/* Number of FATs. 

*/ 

unsigned int RootEntries; 

/* Max number of root directory entries. 

*/ 

unsigned int Sectors; 

/* Number of sectors. 

*/ 

unsigned char Media; 

/* Media descriptor. 

*/ 

unsigned int SectorsPerFAT; 

/* Number of sectors per FAT 

*/ 

unsigned int SectorsPerTrack; 

/* Number of sectors per track. 

*/ 

unsigned int Pleads; 

/* Number of heads. 

*/ 

unsigned long HiddenSectors; 

/* Number of hidden sectors. 

*/ 

unsigned long LargeSectors; 

/* Number of large sectors. 

*/ 

unsigned int Cylinders; 

/* Number of cylinders. 

*/ 

unsigned char DeviceType; 

/* Physical layout, as shown below. 

*/ 

unsigned int DeviceAttr; 

/* Further description, as shown below. 

*/ 


Possible values for DeviceType: 


Value 

Meaning 

0x0000 

48 TPI floppy disk drive 

0x0001 

96 TPI floppy disk drive 

0x0002 

720K 3 J /2-inch disk drive 

0x0003 

8-inch single-density floppy disk drive 

0x0004 

8-inch double-density floppy disk drive 

0x0005 

Hard disk 

0x0006 

Tape drive 

0x0007 

Other or unknown 


Possible values for DeviceAttr, which may be combined: 

Value Meaning 

0x0001 Removable medium 
0x0002 Medium detects changes 


♦ Purpose 

Writes to a particular track on a disk drive. 
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♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrBuffer , PtrCommand, 0x0044, 0x0008, 
DevHandle) 


Parameter 

unsigned char far *Ptr.Buffer 
unsigned char far *PtrCommand 


unsigned short DevHandle 


♦ Structures 

struct Command 

{ 

unsigned char Command; /* 

/* 

unsigned int Head; /* 

unsigned int Cylinder; /* 

unsigned int FirstSector; /* 

unsigned int Sectors; /* 

struct 

{ 


unsigned int SectorNumber; 
unsigned int SectorSize; 

} 

TrackTable[N]; 

}; 


Meaning 

Pointer to buffer containing data 

Pointer to structure described 
below 

Handle previously returned by 
DosOpen 


Value 1 = contains consecutive sectors */ 
beginning with 1; value 0 = otherwise. */ 
Head to which to write. */ 

Cylinder to which to write. */ 

Start sector, from zero. */ 

Number of sectors to write to cylinder. */ 

/* Sector number. */ 

/* Sector size. */ 

/* For each consecutive sector */ 

/* on the track. */ 


Category 08h, 
Function 45h: 
Format Verify 


* Purpose 

Formats and verifies a track on a drive. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrCommand, 0x0045, 0x0008, 
DevHandle) 

Parameter Meaning 

unsigned char far *PtrCommand Pointer to structure described 

below 

unsigned short DevHandle Handle previously returned by 

DosOpen 
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♦ Structures 

struct Command 

{ 

unsigned char Command; /* Value 1 = contains consecutive sectors */ 

/* beginning with 1; value 0 = otherwise. */ 
unsigned int TrackHead; /* Head to which to write. */ 

unsigned int TrackCylinder; /* Cylinder to which to write. */ 

unsigned int Reserved; /* Not used by this function. */ 

unsigned int Sectors; /* Number of sectors to write on cylinder. */ 

struct 

{ 

unsigned char Cylinder; /* Cylinder number. */ 

unsigned char Head; /* Head number. */ 

unsigned char SectorlD; /* Sector identifier. */ 

unsigned char BytesSector; /* Bytes per sector, as shown below. */ 

} 

FormatTabie[N]; /* For each sector on the track. */ 

}; 

Possible values for BytesSector: 


Value Meaning 

0x0000 128 bytes per sector 

0x0001 256 bytes per sector 

0x0002 512 bytes per sector 

0x0003 1024 bytes per sector 


Category 08h, 

Function 631k $ Purpos© 

Get Device Returns device parameters for a disk drive. 


Parameters 


♦ Calling Protocol 


unsigned int pascal far DosDevlOCtl (PtrBPB, PtrCommand, 0x0063, 0x0008, 


DevHandle) 


Parameter Meaning 

unsigned char far *PtrBPB Pointer to structure described 

below 

unsigned char far *PtrCommand Pointer to variable containing one 

of the values shown below 
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unsigned short DevHandle Handle previously returned by 

DosOpen 

Values for *PtrCommand : 

Value Meaning 

0x0000 Return recommended BIOS parameter block for drive 
0x0001 Return block for medium now inserted in drive 

♦ Structures 

struct BPB 

{ 

unsigned int BytesPerSector; /* Bytes per sector. *1 

unsigned char SectorsPerCluster; /* Sectors per cluster. *1 

unsigned int ReservedSectors; /* Reserved sectors. */ 

unsigned char FATs; /* Number of FATs, */ 

unsigned int RootEntries; /* Max number of root directory entries. */ 

unsigned int Sectors; /* Number of sectors. */ 

unsigned char Media; /* Media descriptor. */ 

unsigned int SectorsPerFAT; /* Number of sectors per FAT */ 

unsigned int SectorsPerTrack; /* Number of sectors per track. */ 

unsigned int Heads; /* Number of heads. *1 

unsigned long HiddenSectors; /* Number of hidden sectors. *1 

unsigned long LargeSectors; /* Number of large sectors. *1 

unsigned int Cylinders; /* Number of cylinders. */ 

unsigned char Device'Type; /* Physical layout, as shown below. */ 

unsigned int DeviceAttr; /* Further description, as shown below. */ 

}; 

Possible values for DeviceType: 

Value Meaning 

0x0000 48 TP I floppy disk drive 

0x0001 96 TP I floppy disk drive 

0x0002 720K 3 ^-inch disk drive 

0x0003 8-inch single-density floppy disk drive 

0x0004 8-inch double-density floppy disk drive 

0x0005 Hard disk 

0x0006 Tape drive 

0x0007 Other or unknown 
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Category Q8h, 
Function 64h: 
Read Track 


Possible values for DeviceAttr, which may be combined: 

Value Meaning 

0x0001 Removable medium 

0x0002 Medium detects changes 


♦ Purpose 

Reads a track on a disk drive. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrBuffer , PtrCommand, 0x0064, 0x0008, 
DevHandle) 

Parameter Meaning 

unsigned char far *PtrBuffer Pointer to buffer to which to write 

unsigned char far *PtrCommand Pointer to structure described 

below 

unsigned short DevHandle Handle previously returned by 


DosOpen 

♦ Structures 

struct Command 

{ 

unsigned char Command; /* Value 1 = contains consecutive sectors */ 

/* beginning with 1; value 0 = otherwise. */ 
unsigned int Head; /* Head from which to read. */ 

unsigned int Cylinder; /* Cylinder from which to read. */ 

unsigned int FirstSector; /* Start sector, from zero. */ 

unsigned int Sectors; /* Number of sectors to read from cylinder. */ 

struct 

{ 

unsigned int SectorNumber; /* Sector number. */ 

unsigned int SectorSize; /* Sector size. */ 

} /* For each consecutive sector */ 

TrackTable[N]; /* on the track. */ 

)■ 
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Category 08h, 
Function 65h: 
Verify Track 


* Purpose 

Verifies an operation on a drive. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrCommand, 0x0065, 0x0008, 
DevHandle) 


Parameter 


Meaning 


unsigned char far *PtrCommand Pointer to structure described 

below 


unsigned short DevHandle 


Handle previously returned by 
DosOpen 


♦ Structures 

struct Command 

unsigned char Command; /* Value 1 = contains consecutive sectors 

/* beginning with 1; value 0 = otherwise, 
unsigned int Head; /* Head on which to perform verify, 

unsigned int Cylinder; /* Cylinder on which to perform verify, 

unsigned int FirstSector; /* Start sector, from zero, 
unsigned int Sectors; /* Number of sectors to verify on cylinder. 


struct 

{ 

unsigned int SectorNumber; 
unsigned int SectorSize; 

} 

TrackTable[N]; 


/* Sector number. 

/* Sector size. 

/* For each consecutive sector 
/* on the track. 


Category 09: Physical Disk Control 


Category 09h, 
Function 009k 
Lock Physical 
Drive 


♦ Purpose 

Prevents other processes from accessing a disk drive on any level. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (0L, PtrCommand , 0x0000, 0x0009, 
DevHandle) 
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Parameter 

unsigned char far *PtrCommand 
unsigned short DevHandle 


Meaning 

Pointer to reserved value zero 

Handle previously returned by 
DosOpen 


Category 09Bi, 

Function 01 hr ♦ purpose 

Unlock Physical Makes a disk drive accessible to other processes. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrCommand, 0x0001,0x0009, 
DevHandle) 


Parameter Meaning 

unsigned char far *PtrCommand Pointer to reserved value zero 

unsigned short DevHandle Handle previously returned by 

DosOpen 


Category 09h, 
Function 44h: 
Write Physical 
Track 


♦ Purpose 

Writes to a disk drive, from an offset from the beginning of the physical 
drive. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrBuffer , PtrCommand , 0x0044, 0x0009, 
DevHandle) 


Parameter Meaning 

unsigned char far *PtrBuffer Pointer to buffer with data to write 

unsigned char far *PtrCommand Pointer to structure described 

below 


unsigned short DevHandle Handle previously returned by 

DosOpen 

♦ Structures 

struct Command 

{ 

unsigned char Command; /* Value 1 = contains consecutive sectors */ 

/* beginning with 1; value 0 = otherwise. */ 
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unsigned int Head; 
unsigned int Cylinder; 
unsigned int FirstSector; 
unsigned int Sectors; 
struct 


/* Head to which to write. 

/* Cylinder to which to write. 

/* Start sector, from zero. 

/* Number of sectors to write to cylinder. 


unsigned int SectorNumber; /* Sector number, 

unsigned int SectorSize; /* Sector size, 

j /* For each consecutive sector 

TrackTable[N]; /* on the track. 

}; 


*/ 

*/ 

*1 

*/ 


*/ 

*/ 

*/ 

*7 


Category 09h, 
Function 63h: 
Get Physical 
Device 
Parameters 


♦ Purpose 

Returns device parameters for an entire physical disk drive. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrBlock , PtrCommand, 0x0063, 0x0009, 
DevHandle) 


Parameter 

unsigned char far *PtrBlock 

unsigned char far *PtrCommand 
unsigned short DevHandle 


♦ Structures 

struct Block 

{ 

unsigned int Reservedl; 
unsigned int Cylinders; 
unsigned int Heads; 
unsigned int SectorsPerTrack; 
unsigned int Reserved2; 
unsigned int Reserved3; 
unsigned int Reserved4; 
unsigned int Reserved5; 

}; 


Meaning 

Pointer to structure described 
below 

Pointer to reserved value zero 

Handle previously returned by 
DosOpen 


/* Must be zero. *1 

I* Number of cylinders. */ 

/* Number of heads. */ 

/* Number of sectors per track. */ 
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Category 09h, 
Function 64h; 
Read Physical 
Track 


Category 09h, 
Function 65h: 
Verify Physical 
Trask 


♦ Purpose 

Reads from a track referenced by its offset from the start of the physical 
disk drive. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl ( PtrBuffer , PtrCommand, 0x0064, 0x0009, 
DevHandle) 

Parameter Meaning 

unsigned char far *PtrBuffer Pointer to data to read 

unsigned char far *PtrCommand Pointer to structure described 

below 

unsigned short DevHandle Handle previously returned by 

DosOpen 

♦ Structures 

struct Command 

{ 

struct 

{ 


unsigned char Command; 

/* Value 1 = contains consecutive sectors 

*7 


/* beginning with 1; value 0 = otherwise. 

*/ 

unsigned int Head; 

/* Head from which to read. 

*/ 

unsigned int Cylinder; 

/* Cylinder from which to read. 

*/ 

unsigned int FirstSector; 

/* Start sector, from zero. 

*/ 

unsigned int Sectors; 

/* Number of sectors to read from cylinder. 

*/ 

struct 

{ 

unsigned int SectorNumber; /* Sector number. 

*/ 

unsigned int SectorSize; 

/* Sector size. 

*/ 

} 

/* For each consecutive sector 

*/ 

TrackTable[N]; 

/* on the track. 

*/ 


}; 


♦ Purpose 

Verifies operations on a disk drive, from a location specified as an offset 
from the beginning of the physical drive. 
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♦ Sailing Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrCommand, 0x0065, 0x0009, 
DevHandle) 


Parameter 

unsigned char far *PtrCommand 
unsigned short DevHandle 


Meaning 

Pointer to structure described 
below 

Handle previously returned by 
DosOpen 


♦ Structures 

struct Command 

{ 

unsigned char Command; 

unsigned int Head; 
unsigned int Cylinder; 
unsigned int FirstSector; 
unsigned int Sectors; 
struct 


/* Value 1 = contains consecutive sectors 
/* beginning with 1; value 0 = otherwise. 
/* Head on which to perform verify. 

/* Cylinder on which to perform verify. 

/* Start sector, from zero. 

/* Number of sectors to verify on cylinder. 


{ 

unsigned int SectorNumber; 
unsigned int SectorSize; 

} 

TrackTable[N]; 


/* Sector number. 

/* Sector size. 

/* For each consecutive sector 
/* on the track. 


*/ 

*/ 

*/ 

*/ 

*/ 

*/ 


*/ 

*/ 

*/ 

*/ 



Function 40h: ♦ Purpose 

Register Monitor Registers a monitor. 

♦ Calling Protocol „ 

unsigned int pascal far DosDevlOCtl ( Ptrlnfo , PtrCommand, 0x0040, OxOOOA, 
DevHandle) 


Parameter Meaning 

unsigned int far *PtrInfo Pointer to structure described 

below 

unsigned char far *PtrCommand Pointer to reserved value zero 
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unsigned short DevHandle Handle previously returned by 


DosOpen 

* Structures 

struct Info 

{ 

unsigned int Position; /* Flag used by DosMonReg, as below. */ 

unsigned int Index; /* Device-specific value. */ 

unsigned long Buffer; /* Input buffer used by DosModRead. */ 

unsigned int Offset; /* Offset to output buffer used by */ 

}l /* DosMonWrite. */ 



Function Qlh: 
Flush Input 


♦ Purpose 

Flushes an input buffer. 


♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrCommand, 0x0001, OxOOOB, 
DevHandle) 


Parameter Meaning 

unsigned char far *PtrCommand Pointer to reserved value zero 

unsigned short DevHandle Handle previously returned by 

DosOpen 


Category OBh, 

Function 02h' ♦ Purpose 

Flush Output Flushes an output buffer. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrCommand, 0x0002, OxOOOB, 
DevHandle ) 

Parameter Meaning 

unsigned char far *PtrCommand Pointer to reserved value zero 

unsigned short DevHandle Handle previously returned by 

DosOpen 
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Category GBh, 
Function 60h: 
Query Monitor 
Support 


♦ Purpose 

Queries a device driver for monitor support. Return value of zero indicates 
that device monitors are supported. 

♦ Calling Protocol 

unsigned int pascal far DosDevlOCtl (OL, PtrCommand , 0x0060, OxOOOB, 
DevHandle) 

Parameter Meaning 

unsigned char far *PtrCommand Pointer to reserved value zero 

unsigned short DevHandle Handle previously returned by 

DosOpen 


















APPENDIX D 


OS/2 API 
Error Codes 


This appendix lists the error codes that can be returned by the OS/2 
API functions. The error number is the actual numeric value returned 
directly by the function. Several API functions do not return values 
(such as DosEnterCritSec). Most functions, however, return an 
unsigned int value. If this value is 0, the function was successful; other¬ 
wise, the return value is a code for a specific error condition. 
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The error identifier refers to the constant definition for the error code 
contained in an OS/2 header file (the name of the header file supplied with 
the Microsoft C compiler is BSEERR.H; the header supplied with the 
macro assembler is BSEERR.INC). If you want to use these identifiers in 
your program rather than the numeric values, you must include the defini¬ 
tions, as follows: 

#define INCL_DOSERRORS 
#include <os2.h> 

Note that the error-code constant definitions are also automatically 
included if you define INCL_BASE, which forces inclusion of all kernel 
and subsystem definitions. 


DUMBER 

IDENTIFIER 

EXPLANATION 

0 

NO_ERROR 

No error 

1 

ERROR_INVALID_FUNCTION 

Invalid function code 

2 

EEROR_FILE_NOT_FOUND 

File not found 

3 

ERROR_PATH_NOT_FOUND 

Path not found 

4 

ERRQR_TOO_MANY_OPEN_FILES 

Too many open files 

5 

ERROR_ACCESS_DENIED 

Access denied 

6 

ERROR_INVALID_HANDLE 

Invalid handle 

7 

ERROR_ARENA_TRASHED 

Corrupted data structure in memory 

8 

ERROR_NOT_ENOUGH_MEMORY 

Not enough memory 

9 

ERROR_INVALID_BLOCK 

Bad block 

10 

ERROR_BAD_ENVIRONMENT 

Bad environment 

11 

ERROR_BAD_FORMAT 

Bad format 

12 

ERROR_INVALID_ACCESS 

Invalid access 

13 

ERROR_INVALID_DATA 

Invalid data 

15 

ERROR_INYALID_DRIVE 

Invalid drive 

16 

ERROR_CURRENT_DIRECTORY 

Error in the current directory 

17 

ERROR_NOT_SAME_DEVICE 

Not the same device 

18 

ERROR_N 0_MORE_FILES 

No more files 

19 

ERROR_WRITE_PROTECT 

Write-protect error 

20 

ERROR_BAD_UNIT 

Bad unit number 
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NUMBER 

IDENTIFIER 

EXPLANATION 

21 

ERRQR_NOT_READY 

Drive not ready 

22 

ERROR_BAD_COMMAND 

Bad command 

23 

ERROR_CRC 

CRC error 

24 

ERROR JBAD_LENGTH 

Bad length 

25 

ERROR_SEEK 

Seek error 

26 

ERROR_N OT_DOS_DISK 

Not a DOS or OS/2 disk 

27 

ERROR_SECTOR_NOT_FOUND 

Sector not found 

28 

ERROR_OUT_OF_PAPER 

Out of paper 

29 

ERROR_WRITE_FAULT 

Write fault 

30 

ERROR_READ_FAULT 

Read fault 

31 

ERROR_GEN_FAILURE 

General failure 

32 

ERROR_SHARING_VIOLATION 

Sharing violation 

33 

ERROR_LOCK_VIOLATION 

Lock violation 

34 

ERROR_WRONG_DISK 

Wrong disk 

35 

ERROR_FCB_UN AVAILABLE 

FCB unavailable 

36 

ERROR_SHARING_BUFFER_EXCEEDED 

Sharing buffer exceeded 

50 

ERROR_NOT_SUPPORTED 

Not supported 

80 

ERROR_FILE_EXISTS 

File already exists 

81 

ERROR_DUP_FCB 

Duplicate FCB found 

82 

ERROR_C ANN OT_MAKE 

Cannot make 

83 

ERROR_FAIL_I24 

INT 24 fail action 

84 

ERROR_OUT_OF_STRUCTURES 

Out of data structures (internal) 

85 

ERROR_ALREADY_ASSIGNED 

Already assigned 

86 

ERROR_INVALID_PASSWORD 

Invalid password 

87 

ERROR_INVALID_PARAMETER 

Invalid parameter 

88 

ERROR_NET_WRITE_FAULT 

Network write error 

89 

ERROR_N 0_PR0C_SL0TS 

No process slots assignable, 
cannot create thread 

90 

ERROR_NOT_FROZEN 

Process not frozen 

91 

ERR_TSTOVFL 

Timer service table overflow 
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NUMBER 

IDENTIFIER 

EXPLANATION 

92 

ERR_TSTDUP 

Timer service table duplicate 

93 

ERROR_NO_ITEMS 

No items to process 

95 

ERROR_INTERRUPT 

Interrupted system call 

100 

ERROR_TOO_MANY_SEMAPHORES 

Too many semaphores open 

101 

ERROR_EXCL_SEM_ALREADY_OWNED 

Exclusive semaphore already 
owned 

102 

ERROR_SEM_IS_SET 

Cannot close set semaphore 

103 

ERROR_TOO_MANY_SEM_REQUESTS 

Too many extant requests for 
exclusive semaphore 

104 

ERROR_INVALID_ATJNTERRUPT_TIME 

Operation invalid during 
interrupt time 

105 

ERROR_SEM_OWNER_DIED 

Semaphore owner died holding 
semaphore 

106 

ERROR_SEM_USER_LIMIT 

Limit on number of semaphore 
users exceeded 

107 

ERROR_DISK_CH AN GE 

Disk in drive A must be 
changed 

108 

ERROR_DRIVE_LOCKED 

Drive locked by other process 
and inaccessible 

109 

ERROR_BROKEN_PIPE 

Process reading the pipe has 
died 

110 

ERROR_OPEN_FAILED 

Open/create function failed on 
command 

111 

ERROR_BUFFER_OVERFLOW 

Output buffer too small for 
needs of system call 

112 

ERROR_DISK_FULL 

Insufficient disk space 

113 

ERROR_N G_MORE_SEARCH_H ANDLES 

Search handle limit exceeded 

114 

ERROR_INVALID_TARGET_HANDLE 

Could not use duplicate handle 
value 

115 

ERROR_PROTECTION_VIOLATION 

Value outside user’s address 
space 

116 

ERROR_VIOKBD_REQUEST 

Internal error in system call 

117 

ERROR_INVALID_CATEGORY 

Undefined IOCTL category 



OS/2 API Error Codes 


DUMBER 

IDENTIFIER 

EXPLANATION 

118 

ERROR_INVALID_VERIFY_SWITCH 

Invalid value for switch 

119 

ERROR_BAD_DRIVER_LEVEL 

Invalid value level (other than level 4) 

120 

ERROR_CALL_NOT_IMPLEMENTED 

Internal error 

121 

ERROR_SEM_TIMEOUT 

Timeout while waiting for a 
semaphore 

122 

ERROR_INSUFFICIENT_BUFFER 

System call input buffer too small 

123 

ERROR_INYALID_NAME 

Invalid form for file name 

124 

ERROR_INVALID_LEVEL 

Invalid request-level packet 

125 

ERROR_NO_VOLUME_LABEL 

Target disk lacks volume label 

126 

ERROR_MOD_NOT_FOUND 

Module not found 

111 

ERROR_PROC_NOT_FOUND 

Entry point not found 

128 

ERROR_WAIT_NO_CHILDREN 

No child process for which to wait 

129 

ERROR_CHILD_NOT_COMPLETE 

No child processes have died 

130 

ERROR_DIRECT_ACCESS_HANDLE 

Invalid handle for direct disk access 

131 

ERROR_NEGATIVE_SEEK 

Attempted seek prior to beginning 
of file 

132 

ERROR_SEEK_ON_DEVICE 

Cannot seek on character device 

133 

ERRQR_IS_JOIN_TARGET 

Invalid operation on joined disk 

134 

ERROR_IS_J OINED 

Disk is joined 

135 

ERROR_IS_SUBSTED 

Substituted directory 

136 

ERROR_NOT_JOINED 

Disk not joined 

137 

ERROR_NOT_SUBSTED 

Directory not substituted 

138 

ERROR_J OIN_TQ_J OIN 

Disk already joined 

139 

ERROR_SUBST_TO_SUBST 

Directory already substituted 

140 

ERROR_JOIN_TO_SUBST 

Attempted join to substituted 
directory 

141 

ERROR_SUBST_TO_JOIN 

Attempted substitute to joined disk 

142 

ERROR_BUSY_DRIVE 

Busy drive 

143 

ERROR_SAME_DRIVE 

Same drive specified 

144 

ERROR_DIR_NOT_ROOT 

Operation must be upon root 
directory 
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NUMBER 

IDENTIFIER 

EXPLANATION 

145 

ERROR_DIR_NOT_EMPTY 

Directory not empty 

146 

ERRQR_IS_SUBST_PATH 

Error in substituted directory path 

147 

ERROR_IS_JOIN_PATH 

Error in joined drive path 

148 

ERROR_PATH_BUSY 

Busy path 

149 

ERROR_IS_SUBST_TARGET 

Substituted directory is invalid 
target 

150 

ERROR_S Y STEM_TRACE 

System trace error 

151 

ERROR_INVALIDJEVENT_COUNT 

Error in DosMuxSemWait count 
field 

152 

ERROR_TOO_MANY_MUXWAITERS 

Limit exceeded 

153 

ERROR_INVALID_LIST_FORMAT 

Invalid list format 

154 

ERROR_LABEL_TOO_LONG 

Volume label too long 

155 

ERROR_TOO_MANY_TCBS 

Cannot create another thread 
control block 

156 

ERROR_SIGNAL_REFUSED 

Signal was refused 

157 

ERROR_DISCARDED 

Segment was discarded 

158 

ERROR_NOT_LOCKED 

Segment was not locked 

159 

ERROR_BAD_THREADID_ADDR 

Bad thread ID address (internal) 

160 

ERROR_BAD_ARGUMENTS 

Invalid environment pointer 

161 

ERROR_BAD_PATHNAME 

Invalid path name 

162 

ERROR_SIGNAL_PENDING 

Signal already pending 

163 

ERROR_UNCERTAIN_MEDIA 

Disk medium is uncertain 

164 

ERRORJMAX_THRDS_REACHED 

Maximum threads exceeded 

165 

ERRORJV10NITORS_NOT_SUPPORTED 

Monitors not supported 

180 

ERROR_INVALID_SEGMENT_NUMBER 

Invalid segment number (internal) 

181 

ERROR_INVALID_CALLGATE 

Invalid call gate (internal) 

182 

ERROR_INVALID_ORDINAL 

Invalid ordinal (internal or .EXE) 
error 

183 

ERROR_ALREADY_EXISTS 

Shared segment already exists 

184 

ERROR_NO_CHILD_PROCESS 

No child processes to wait for 
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NUMBER 

IDENTIFIER 

EXPLANATION 

185 

ERROR_CHILD_ALI VE_N OWAIT 

Specified no wait but live child 
exists 

186 

ERROR_INVALID_FLAG_NUMBER 

Invalid flag number 

187 

ERROR_SEM_NOT_FOUNB 

No such system semaphore 

188 

ERROR_INVALID_STARTIN G_CODESEG 

Invalid starting code segment 
in .EXE file 

189 

ERROR_INVALID_STACKSEG 

Invalid stack segment in .EXE 
file 

190 

ERROR_INVALID_MODULETYPE 

Invalid module type in .EXE 
file 

191 

ERROR_INVALID_EXE_SIGNATURE 

Invalid signature in .EXE file 

192 

ERROR_EXE_MARKED_INVALID 

.EXE file marked invalid 

193 

ERROR_BAD_EXE_FORMAT 

Bad format in .EXE file 

194 

ERROR_ITERATED_DATA_EXCEEDS_64K 

Iterated data exceeds 64K in 
.EXE file 

195 

ERROR_IN VALID_MIN ALLOCSIZE 

Invalid minimum allocation 
size specified in .EXE file 

196 

ERROR_BYNLINK_FROM_INVALID_RING 

Dynamic link from invalid ring 
in .EXE file 

197 

ERROR_IOPL_N OT_EN ABLED 

IOPL is not enabled 

198 

ERROR_INVALID_SEGDPL 

Segment DPL value other than 
3 in .EXE file 

199 

ERROR_AUTODATASEG_EXCEEDS_64K 

Automatic data segment 
exceeds 64K in .EXE file 

200 

ERROR_RING2SEG_MUST_BE_MOVABLE 

Ring 2 segment not movable in 
.EXE file 

201 

ERROR_RELOC_CHAIN_XEEDS_SEGLIM 

Relocation chain exceeds limit 
in .EXE file 

202 

ERROR_INFLOOP_IN_RELOC_CHAIN 

Infinite loop in relocation 
chain in .EXE file 

203 

ERROR_EN WAR_N OT_F OUND 

Environment variable not 
found 

204 

ERROR_NOT_CURRENT_CTRY 

Not current country 
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NUMBER 

IDENTIFIER 

EXPLANATION 

205 

ERROR_N 0_SIGN AL_SENT 

No signal was sent 

206 

ERROR_FILENAME_EXCED_RANGE 

File name exceeded range 

207 

ERROR_RING2_STACK_IN_USE 

Ring 2 stack in use 

208 

ERROR_META_EXPANSION_TOO_LONG 

Meta expansion too long 

209 

ERROR_INVALID_SIGNAL_NUMBER 

Invalid signal number 

210 

ERROR_THREAD_l_INACTIVE 

Thread 1 is inactive 

211 

ERROR_INFO_NOT_AVAIL 

Information not available 

212 

ERROR_LOCKED 

Locked 

213 

ERROR_BAD_DYNALINK 

Bad dynamic-link module 

214 

ERROR_TOO_MANY_MQDULES 

Module limit exceeded 

215 

ERROR_NESTING_NOT_ALLOWED 

Nesting not allowed 

303 

ERROR_INVALID_PROCID 

Invalid process ID 

304 

ERROR_IN VALID_PDELTA 

Change in priority level is invalid 

305 

ERROR_NOT_DESCENDANT 

Target process not a descendant 

306 

ERROR_N OT_SESSION_MAN AGER 

Caller not session manager 

307 

ERROR_INVALID_PCLASS 

Invalid priority class 

308 

ERROR_INVALID_SCOPE 

Invalid scope 

309 

ERROR_INVALID_THREADID 

Invalid thread ID 

310 

ERROR_DOSSUB_SHRINK 

Cannot shrink suballocated 
segment 

311 

ERROR_DOSSUB_N OMEM 

Out of memory in suballocated 
segment 

312 

ERROR_DOSSUB_OVERLAP 

Invalid element overlap in 
DosSubFree 

313 

ERRQR_DOSSUB_BADSIZE 

Invalid element size parameter 

314 

ERROR_DOSSUB_BADFLAG 

Invalid flag parameter 

315 

ERROR_DOSSUB_BADSELECTOR 

Invalid segment selector 

316 

ERROR_MR_MSG_TOO_LONG 

Message too long for buffer 

317 

ERROR_MR_MID_NOT_FOUND 

Message ID not found 

318 

ERROR_MR_UN_ACC_MSGF 

Cannot access the message file 
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NUMBER 

IDENTIFIER 

EXPLANATION 

319 

ERROR_MR_IN V_MSGF_F QRMAT 

Invalid message file format 

320 

ERROR_MR_IN V_IV COUNT 

Invalid insertion variable count 

321 

ERRQR_MR_UN_PERFORM 

Unable to perform function 

322 

ERROR_TS_WAKEUP 

Function has returned before 
specified time has elapsed 

323 

ERROR_TS_SEMHANDLE 

Invalid system semaphore 

324 

ERROR_TS_N OTIMER 

No timers available 

326 

ERROR_TS_HANDLE 

Invalid timer handle 

327 

ERROR_TS_DATETIME 

Invalid date or time 

328 

ERROR_SYS_INTERNAL 

Internal system error 

329 

ERROR_QUE_CURRENT_NAME 

Nonexistent queue name 

330 

ERROR_QUE_PROC_N OT_OWNED 

Queue not owned by calling process 

331 

ERROR_QUE_PROC_OWNED 

Queue owned by current process 

332 

ERROR_QUE_DUPLICATE 

Queue name already exists 

333 

ERROR_QUE_ELEMENT_NOT_EXIST 

Queue element does not exist 

334 

ERROR_QUE_NO_MEMORY 

Insufficient memory 

335 

ERROR_QUE_INVALID_NAME 

Invalid queue name 

336 

ERRQR_QUE_INVALID_PRIQRITY 

Invalid element priority value 

337 

ERROR_QUE_INVALID_HANDLE 

Invalid queue handle 

338 

ERROR_QUE_LINK_NOT_FOUND 

Queue link not found (internal) 

339 

ERROR_QUE_MEMORY_ERROR 

Queue memory error (internal) 

340 

ERROR_QUE_PREV_AT_END 

Previous element was at end of 
queue 

341 

ERROR_QUE_PROC_NO_ACCESS 

Caller does not have access to 
queue 

342 

ERROR_QUE_EMPTY 

Queue is empty 

343 

ERROR_QUE_NAME_N OT_EXIST 

No queue by this name exists 

344 

ERROR_QUE_NOT_INITIALIZED 

Queue is not initialized 

345 

ERROR_QUE_UNABLE_TO_ACCESS 

Unable to access queue 

346 

ERROR_QUE_UNABLE_TO_ADD 

Unable to add new queue (internal) 
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NUMBER 

IDENTIFIER 

347 

ERROR_QUE_UNABLE_TO_INIT 

349 

ERROR_VIO_INVALID_MASK 

350 

ERROR_VIO_PTR 

351 

ERROR_VIO_APTR 

352 

ERROR_VIO_RPTR 

353 

ERRQR_VIO_CPTR 

354 

ERROR_VIO_LPTR 

355 

ERROR_VIO_MODE 

356 

ERROR_VIO_WIDTH 

357 

ERROR_VIO_ATTR 

358 

ERROR_VIO_ROW 

359 

ERROR_VIO_COL 

360 

ERROR_VIO_TOPROW 

361 

ERRQR_VIO_BQTROW 

362 

ERROR_VIO_RIGHTCOL 

363 

ERROR_VIO_LEFTCOL 

364 

ERROR_SCS_CALL 

365 

ERROR_SCS_VALUE 

366 

ERROR_VIO_WAIT_FLAG 

367 

ERROR_VIO_UNLOCK 

368 

ERROR_SGS_NOT_SESSION_MGR 

369 

ERROR_SMG_INVALID_SGID 

369 

ERROR_SMG_INVALID_SESSION_ID 

370 

ERROR_SMG_NOSG 

370 

ERROR_SMG_NO_SESSIONS 

371 

ERROR_SMG_GRP_NOT_FOUND 

371 

ERROR_SMG_SESSION_NOT_FOUND 

372 

ERROR_SMG_SET_TITLE 

373 

ERROR_KBD_PARAMETER 


EXPLANATION 

Unable to initialize queue (internal) 
Invalid Vio function mask 
Invalid pointer to parameter 
Invalid pointer to attribute 
Invalid pointer to row 
Invalid pointer to column 
Invalid pointer to length 
Unsupported display mode 
Invalid cursor width 
Invalid cursor attribute 
Invalid row 
Invalid column 
Invalid value for top row 
Invalid value for bottom row 
Invalid value for right column 
Invalid value for left column 
Only session manager may call 
Value not for save or restore 
Invalid wait flag setting 
Screen not previously locked 
Only session manager may call 
Invalid screen group ID 
Invalid session ID 
Screen group not available 
No sessions available 
Screen group not found 
Session not found 
Title cannot be changed 
Invalid parameter to Kbd call 
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375 

376 

377 

378 

379 

380 

381 

382 

383 

384 

385 

386 

387 

388 

389 

390 

391 

392 

393 

394 

395 

396 

397 

398 
398 
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IDENTIFIER 
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ERROR_KBB_N 0_BE VICE 

ERROR_KBB_INYALID_IOWAIT 

ERROR_KBD_INYALIB_LENGTH 

ERROR_KBD_INYALIB_ECBO_MASK 

ERROR_KBB_INVALIB_INPUT_MASK 

ERROR_MON_INVALIB_PARMS 

ERROR_MON_IN VALID_BE VN AME 

ERROR_MON_INVALIB_HANBLE 

ERROR_MON_BUFFER_TOO_SMALL 

ERROR_MON_BUFFER_EMPTY 

ERROR_MON_BATA_TOO_LARGE 

ERROR_MOUSE_NO_DEYICE 

ERROR_MOU SE_IN V_H ANDLE 

ERROR_MOUSE_INV_PARMS 

ERROM_MOUSE_CANT_RESET 

ERROR_MOUSE_BISPLAY_PARMS 

ERROR_MOUSE_INY_MOBULE 

ERROR_MOUSE_INY_ENTRY_PT 

ERROR_MOU SE_IN Y_M ASK 

NO_ERROR_MOUSE_NO_BATA 

NO_ERROR_MOUSE_PTR_BRAWN 

ERROR_INYALIB_FREQUENCY 

ERROR_NLS_NO_COUNTRY_FILE 

ERROR_NLS_OPEN_FAILED 

ERROR_NLS_NO_CTRY_CODE 

ERROR_NO_COUNTRY_OR_COBEPAGE 


Out of system handles 

Invalid I/O wait flag value 

Invalid length for keyboard 

Invalid echo mode mask 

Invalid input mode mask 

Invalid parameters to monitor 
call 

Invalid device name 

Invalid device handle 

Buffer is too small 

Buffer is empty 

Data too large 

No mouse attached 

Mouse device closed, handle 
invalid 

Parameters out of range or 
invalid 

Function assigned, cannot reset 

Invalid parameters for current 
display mode 

Module not found 

Entry point not valid 

Function mask invalid 

No mouse data 

OK, mouse pointer drawn 

Invalid beep frequency 

Cannot locate COUNTRY. SYS 

Cannot open COUNTRY.SYS 

Country code not found 

Country code or code page not 
found 
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399 

ERROR_N3LS_TABLE_TRUN GATED 

Buffer too small to hold table 

400 

ERROR_NLS_BAD_T¥PE 

Selector type does not exist 

401 

ERROR_NLS_TYPE_NOT_FOUND 

Selector type not in file 

402 

ERROR_VIO_SMG_ONLY 

Only session manager may call 

403 

ERROR_VIO_INVALID_ASCIIZ 

Invalid string length 

404 

ERROR_VIO_DEREGI8TER 

No display subsystem previously 
registered within current screen group 

405 

ERROR_VIO_NO_POPUP 

Pop-up not performed 

406 

ERROR_ VI 0_EXISTING_POPUP 

Already a pop-up running 

407 

ERROR_KBD_SMG_ONLY 

Only session manager may call 

408 

ERROR_KBD_INVALID_ASCIIZ 

Invalid string length 

409 

ERROR_KBD_INVALID_MASK 

Invalid function replaced 

410 

ERROR_KBD_REGISTER 

Keyboard register disallowed 

411 

ERROR_KBD_DEREGISTER 

No keyboard subsystem previously 
registered within current screen group 

412 

ERROR_MOUSE_SMG_ONLY 

Only session manager may call 

413 

ERROR_MOUSE_INVALID_ASCIIZ 

Invalid string length 

414 

ERROR_MOU SE_IN VALID_M ASK 

Invalid function replaced 

415 

ERROR_MOUSE_REGISTER 

Mouse register disallowed 

416 

ERROR_MOUSE_OEREGI8TER 

No mouse subsystem previously 
registered within current screen group 

417 

ERROR_SMG_BAD_ACTION 

Invalid action for session manager 

418 

ERROR_SMG_INVALID_CALL 

Redundant call to initialize 

419 

ERROR_SCS_SG_NOTFOUND 

New session number not found 

420 

ERROR_SCS_NOT_SHELL 

Only shell may call 

421 

ERROR_VIO_INVALID_PARMS 

Invalid Vio parameters 

422 

ERROR_VIO_FUNCTION_OWNED 

SavRestoreWait thread already owned 

423 

ERROR_VIO_RETURN 

SavRestoreWait thread freed by other 
thread 

424 

ERROR_SCS_INVALID_FUNCTION 

Caller may not request 

425 

ERROR_SCS_NOT_SESSION_MGR 

Only session manager may call 
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428 

429 

430 

431 

432 

433 

434 

435 

436 

437 

438 

439 

440 

441 

442 

443 

444 

445 

446 


IDENTIFIER 


EXPLANATION 


ERROR_VIO_REGISTER 

ERROR_VIOJVO_MODE_THREAD 


ERROR_YIO_NO_SAYE_RE§T0RE_THD 

ERROR_VIO_IN_BG 

ERROR_VIO_ILLEGAL_DURING_POPUP 

ERROR_SMG_N OT_B ASESHELL 

ERROR_SMG_B AD_STATU SREQ 
ERROR_QUE_INYALID_WAIT 

ERROR_VIO_LOCK 

ERRORJVfOUSEJVYALIDJGWAIT 

ERROR_VIO_INVALID_HANDLE 

ERROR_YIO_ILLEGAL_DURING_LOCK 

ERROR_YIO_IN YALIB_LEN GTH 
ERROR_KBD_INYALID__HANDLE 
ERROR_KBD_N Q_MORE_H ANBLE 


VioRegister disallowed 

No previous call to 
YioModeWait within current 
screen group 

No previous call to 
VioSavRedrawWait within 
current screen group 

Function permitted only 
when process is in 
foreground 

Illegal function call during 
pop-up 

Only base system shell may 
call 

Invalid status was requested 

NoWait parameter out of 
bounds 

Screen already locked 

Invalid parameters for mouse 
I/O wait 

Invalid Vio handle 

Vio function not allowed 
while screen is locked 

Invalid Vio parameter length 

Invalid Kbd handle 

No more Kbd handles 
available 


ERROR_KBD_CANNOT_CREATE_KCB 
ERROR_KBD_CODEPAGE_LOAD_IN COMPL 
ERROR_KBB_INVALID_CODEPAGE_JD 
ERROR_KBD_NO_COBEPAGE_SUPPORT 
ERROR_KBD_FOCUS_REQUIREB 
ERROR_KBD_FOCU S_ALREAO Y_ACTI YE 


Internal keyboard error 

Failed to load code page 

Invalid code-page ID 

No code-page support 

Must have keyboard focus 

Caller already has keyboard 
focus 
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447 

ERROR_KBD_KEYBOARB_BUSY 

Keyboard busy 

448 

ERROR_KBD_INVALID_CODEPAGE 

Invalid code page 

449 

ERROR_KBD_UNABLE_TO_FOCUS 

Failure to get keyboard focus 

450 

ERROR_SMG_SESSION_NON_SELECT 

Session cannot be selected 

451 

ERROR_SMG_SESSION_NOT_FOREGRND 

Caller or child not in 
foreground 

452 

ERROR_SMG_SESSION_NOT_PARENT 

Caller not parent of process 

453 

ERROR_SMG_INVALID_START_MODE 

Invalid “foreground/ 
background” option 

454 

ERROR_SMG_INVALID_RELATED_OPT 

Invalid “related” option 

455 

ERROR_SMG_INVALID_BOND_OPTION 

Invalid “binding” option 

456 

ERROR_SMG_INVALID_SELECT_OPT 

Invalid session “selectable” 
option 

457 

ERROR_SMG_START_IN_BACKGROUND 

Session started in background 

458 

ERROR_SMG_INVALID_STOP_OPTION 

Invalid session stop option 

459 

ERROR_SMG_BAD_RESERVE 

Reserved parameters not zero 

460 

ERROR_SMG_PROCESS_NOT_PARENT 

Session parent process already 
exists 

461 

ERROR_SMG_IN VALI D_D ATA_LEN GTH 

Invalid data length 

462 

ERROR_SMG_NOT_BOUND 

Parent was not bound 

463 

ERROR_SMG_RETRY_SUB_ALLOC 

Request-block option should 
be retried 

464 

ERROR_KBD_DETACHED 

Detached process not allowed 
Kbd call 

465 

ERROR_VIO_DETACHED 

Detached process not allowed 
Vio call 

466 

ERROR_MOU_DETACHED 

Detached process not allowed 
Mou call 

467 

ERROR_VIO_FONT 

Font for this mode not 
available 

468 

ERROR_VIO_USER_FONT 

User font active 

469 

ERROR_VIO_BAD_CP 

Invalid code page 
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470 

ERROR_VIO_NO_CP 

Code page not supported by 
system display 

471 

ERROR_VIO_N A_CP 

Code page not supported by 
current display 

472 

ERROR_INVALID_CODE_PAGE 

Invalid code page 

473 

ERROR_CPLIST_TOO_SMALL 

Code-page list too small 

474 

ERROR_CP_NOT_MOVED 

Code page not moved 

475 

ERROR_MODE_SWITCH_INIT 

Mode switch initialization 

error 

476 

ERROR_CODE_PAGE_NOT_FOUND 

Code page not found 

All 

ERROR_UNEXPECTED_SLOT_RETURNED 

Internal error 

478 

ERROR_SMG_INVALID_TRACE_OPTION 

Invalid start session trace 
indicator 

479 

ERROR_VIO_INTERNAL_RESOURCE 

Vio subsystem internal 
resource error 

480 

ERROR_VIO_SHELL_INIT 

Vio subsystem shell 
initialization error 

481 

ERROR_SMG_NO_HARD_ERRORS 

No session manager hard 
errors 

482 

ERROR_CP_S WIT CH_IN COMPLETE 

Unable to set code page for 
Kbd or Vio subsystem 

483 

ERROR_ VIO_TRAN SPARENT_POP UP 

Error during pop-up 

484 

ERROR_CRITSEC_OVERELOW 

Critical section overflow 

485 

ERROR_CRITSEC_UNDERFLOW 

Critical section underflow 

486 

ERROR_VIO_BAD_RESERVE 

Reserved parameter not zero 

487 

ERROR_INVALID_ADDRESS 

Invalid address 

488 

ERROR_ZERO_SELECTORS_REQUESTED 

No selectors requested 

489 

ERROR_NOT_ENOUGH_SELECTORS_AVA 

Not enough selectors 
available 

490 

ERROR_INVALID_SELECTOR 

Invalid selector 

491 

ERROR_SMG_INVALID_PROGRAM_TYPE 

Invalid program type 

492 

ERROR_SMG_INVALID_PGM_CONTROL 

Invalid program control 
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3.x box. See screen group, real mode 

8088 (processor), 4 

80286 (processor), 4-6, 27-28, 59 

80286 instructions, 73-74 

80386 (processor), 4-6, 27-28, 30, 32 

A 

ABIOS, 91 

addressing mechanisms, 62-64. See 
also virtual memory 
alias segment selectors, 66, 210, 259 
allocation, of memory, 68, 107 
/An (compiler option), 324 
ANSI (command line command), 42 
ANSI escape sequences, 287, 296-297 
API (application program interface), 3, 
8, 49-55 

API.LIB (file), 171-173 
APPEND (command line command), 
42 

/As (compiler option), 324 
assembly language, 129 
ASSIGN (command line command), 42 
attributes (video), 283-285 
/Au (compiler option), 324 
AUTOEXEC.BAT (file), 32-33 

B 

background programs, 10, 15, 22-23, 
155-156. See also TSRs; monitors 
BAT files. See batch files 
batch files, 32-33, 40-45 
bimodal addresses, 90 
BIND (utility), 161-162, 165-167, 
170-173 
bindings, 164 


BIOS 

general, 5, 23-24, 91, 99 
services, 102-103, 107-108, 130-134 
BIOS data area, 102-103, 136 
blocking, 208 

bound programs. See dual-mode 
programs 

BREAK (configuration command), 34, 
42 

BUFFERS (configuration command), 
34 

busy waiting, 208 


C 

/c (compiler option), 117 
Clanguage 
advantages of, 123 
library, 138-141 

using multiple threads in, 187-191 
call gate, 70 

CL (program), 119. See also compiling 
CMD (command line command), 

42-43 

CMD files. See batch files 
CMD.EXE (command interpreter), 17, 
21 

code pages, 273-275 
CODEPAGE (configuration 
command), 34, 274 
COMMAND (command line 
command), 42 

COMMAND.COM (command 
interpreter), 17, 21 
command subtree, 192-194 
commands 

command line, 9, 32, 40-45 
configuration, 32-40 



communication, interprocess. See 
interprocess communication 
communication area, 136-137 
compatibility (of OS/2) 
hardware, 28 
software, 28-32 

compatibility box. See screen group, 
real mode 
compiling, 116-117 
of dual-mode programs, 170-171 
of dynamic-link libraries, 324-325 
COMSPEC (environment variable), 
76-77 

CONFIG.SYS (file), 32-33 
configuration commands, 32-40 
control-break handling, 198, 238-239 
Control-C handling, 198, 238-239 
converting programs (MS-DOS to 
OS/2), 122-138 

COUNTRY (configuration command), 
34, 274 

critical sections (of code), 187, 215-217 
CTTY (command line command), 40 
cursor control, 285-286 
cut-and-paste utility, 342-361 


D 

date management, 272-273 
DEF files. See definition files 
definition files, 148-150, 152-155, 320 
commands, 152-155 
for dynamic-link libraries, 325 
for Presentation Manager programs, 
375 

descriptor, segment, 63-64. See also 
virtual memory 

descriptor table, 63-64. See also virtual 
memory 

DETACH (command line command), 
11,21-22, 43, 155-156, 295,342 
DEVICE (configuration command), 

35, 85, 111, 134 


device control 
direct, 138, 141-147 
functions for, 143-147, 535-594 
low-level, 266-267 
see also DosDevIOCtl 
device drivers, 8, 84-91, 110-111 
device handles, standard, 142-143 
device I/O, 259-263 
device monitors. See monitors 
device names, reserved, 142 
DEVINFO (configuration command), 
34-35, 274 

dialog boxes (Presentation Manager), 
370 

directory management, 263-266 
discardable segments, 255-256 
disk file I/O, 259-263 
disk file management, 263-266 
disk management, 263-266 
DISKCACHE (configuration 
command), 35 

DLL files. See dynamic-link libraries 
DosAllocHuge (API function), 209, 
253, 256-257, 394-395 
DosAllocSeg (API function), 209, 211, 
235, 237, 252, 254-256, 395-396 
DosAllocShrSeg (API function), 209, 
211,219, 222, 253,356, 396 
DosBeep (API function), 278, 396 
DosBufReset (API function), 260, 263, 

396- 397 

DOSCALLS.LIB (import library), 57, 
114-115, 117-118, 326 
DosCaseMap (API function), 274-275, 
397 

DosChdir (API function), 263-264, 

397- 398 

DosChgFilePtr (API function), 
200-201, 260, 262, 398 
DosCLIAccess (API function), 73, 
266-267, 398 

DosClose (API function), 200, 

224-225, 228, 260, 263, 271, 399 



DosCloseQueue (API function), 230, 
232, 234, 236-237, 271, 399 
DosCloseSem (API function), 213, 
218,220-221,270, 399 
DosCreateCSAlias (API function), 66, 
254, 259, 399-400 
DosCreateQueue (API function), 
229-231, 233-234, 271, 400 
DosCreateSem (API function), 213, 
216, 219, 222, 270, 400-401 
DosCreateThread (API function), 178, 
184-186, 189, 267, 401 
DosCWait (API function), 196, 198, 
200-201, 203, 220, 223, 268, 
401-402 

DosDelete (API function), 264-265, 
403 

DosDevConfig (API function), 79, 81, 
83, 266, 403-404 

DosDevIOCtl (API function), 87, 129, 
134, 138, 143-147, 266-267, 404, 
535-593 

DosDupHandle (API function), 200, 
202, 224, 226-228, 260, 262, 271, 
405 

DosEnterCritSec (API function), 185, 
187, 189-190,216, 267,405 
DosErrClass (API function), 277, 
405-406 

DosError (API function), 277-278, 407 
DosExecPgm (API function), 168, 
196-198, 200, 222, 227-228, 268, 
407-408 

DosExit (API function), 122, 185-186, 
196-198, 267-268, 409 
DosExitCritSec (API function), 185, 
187, 189-190,216, 267,409 
DosExitList (API function), 196, 198, 
239, 268, 328, 409-410 
DosFileLocks (API function), 260, 

262, 410 

DosFindClose (API function), 

264-266, 410 


DosFindFirst (API function), 264-266, 

411- 412 

DosFindNext (API function), 264-266, 

412- 414 

DosFlagProcess (API function), 198, 
238-242, 245, 272, 414 
DosFreeModule (API function), 60, 
276, 332, 334,414-415 
DosFreeSeg (API function), 209, 
211-212, 220-221, 234, 236-237, 
252, 255-257, 259, 415 
DosGetCoIlate (API function), 
274-275, 415-416 
DosGetCP (API function), 79, 
274-275, 416 

DosGetCtrylnfo (API function), 79, 
274-275, 416-418 

DosGetDateTime (API function), 77, 
272-273,418 

DosGetDBCSEv (API function), 
274-275,418-419 

DosGetEnv (API function), 77, 251, 
419 

DosGetHugeShift (API function), 253, 
257, 419-420 

DosGetlnfoSeg (API function), 77-78, 
81-83, 136, 185-186, 196, 205, 
251, 267-268, 269, 273, 420-421 
DosGetMachineMode (API function), 
78, 168-170, 251-252, 421 
DosGetMessage (API function), 
274-275, 421-422 

DosGetModHandle (API function), 
276, 422 

DosGetModName (API function), 276, 
423 

DosGetPid (API function), 78, 185, 
196, 242, 245, 267-268, 423 
DosGetProcAddr (API function), 59, 
276, 332-334, 423-424 
DosGetPrty (API function), 59, 79, 
181, 185-186, 196, 267,269, 424 
DosGetSeg (API function), 253, 425 



Index 


DosGetShrSeg (API function), 209, 

211, 221, 223, 253, 356-357, 425 
DosGetVersion (API function), 78, 
251-252, 425 

DosGiveSeg (API function), 209, 211, 
236-237, 253, 426 
DosHoldSignal (API function), 
240-242, 272, 426 
DosInsMessage (API function), 
274-275, 426-427 

DosKillProcess (API function), 193, 
196, 198, 238-239, 269, 427 
DosLoadModule (API function), 59, 
276, 330, 333, 427-428 
DosLockSeg (API function), 253, 256, 

428 

DosMakePipe (API function), 

224-227, 271, 428 

DosMemAvail (API function), 79, 209, 
253, 255, 428-429 

DosMkdir (API function), 264-265, 

429 

DosMonClose (API function), 276, 

341, 352, 357-358,429 
DosMonOpen (API function), 276, 
341,347, 357,429 
DosMonRead (API function), 276, 
340-341,348,357,430-431 
DosMonReg (API function), 276, 341, 
347-348, 357,431-432 
DosMonWrite (API function), 276, 
340-341, 348, 357-358, 432-434 
DosMove (API function), 264-265, 434 
DosMuxSemWait (API function), 213, 
218, 270, 434-435 

DosNewSize (API function), 260, 262, 
435 

DosOpen (API function), 138, 

141-142, 145-146, 199, 201, 
260-261, 270, 436-438 
DosOpenQueue (API function), 
229-230, 234-235, 271, 438 
DosOpenSem (API function), 213, 

216, 221,223,438 


DosPeekQueue (API function), 
230-232, 271, 439-440 
DosPhysicalDisk (API function), 
266-267, 440-441 
DosPortAccess (API function), 
266-267, 441 

DosPTrace (API function), 278, 
441-443 

DosPurgeQueue (API function), 230, 
232, 271, 443-444 
DosPutMessage (API function), 
274-275, 444 

DosQCurDir (API function), 79, 

263- 264, 444 

DosQCurDisk (API function), 51, 54, 
79, 263-264, 445 

DosQFHandState (API function), 79, 
260, 262, 445-446 

DosQFilelnfo (API function), 53-54, 
79, 260, 262, 446-447 
DosQFileMode (API function), 79, 

264- 265, 447-448 
DosQFSInfo (API function), 79, 

120-121, 263-264, 448-449 
DosQHandType (API function), 
224-225, 260, 262, 271, 449-450 
DosQueryQueue (API function), 230, 
232, 271, 450 

DosQVerify (API function), 79, 264, 
266, 450-451 

DosRead (API function), 141, 

224-225, 228, 260-262, 271, 303, 
451 

DosReadAsync (API function), 262, 
451-452 

DosReadQueue (API function), 
230-234, 271, 452-453 
DosReallocFluge (API function), 253, 
257, 453 

DosReallocSeg (API function), 253, 
255-256, 453-454 

DosResumeThread (API function), 
185, 187, 268, 454 



DosRmdir (API function), 264-265, 
454 

DosScanEnv (API function), 77, 251, 
454-455 

DosSearchPath (API function), 
251-252, 265, 455 
DosSelectDisk (API function), 263, 
265, 456 

DosSelectSession (API function), 
204-205, 269,456 
DosSemClear (API function), 213, 

216- 217, 220-222, 270, 456 
DosSemRequest (API function), 213, 

215-218,220-222,270,457 
DosSemSet (API function), 213, 217, 
270, 457 

DosSemSetWait (API function), 214, 
270, 457-458 

DosSemWait (API function), 214, 

217- 218,270,458 
DosSendSignal (API function), 458 
DosSetCp (API function), 274-275, 

459 

DosSetDateTime (API function), 
272-273, 459 

DosSetFHandState (API function), 
261-262, 460 

DosSetFilelnfo (API function), 
261-262, 460-461 

DosSetFileMode (API function), 265, 
461-462 

DosSetFSInfo (API function), 263, 
265, 462-463 

DosSetMaxFH (API function), 
265-266, 463 

DosSetPrty (API function), 181, 
185-186, 193-194, 196,198, 
268-269, 341-342, 357, 463-464 
DosSetSession (API function), 
204-205, 269, 464-465 
DosSetSigHandler (API function), 
197-198, 238, 240-241, 243-244, 
269, 271,465-466 


DosSetVec (API function), 277-278, 
466-467 

DosSetVerify (API function), 265-266, 

467 

DosSleep (API function), 236-237, 
272-273, 467 

DosStartSession (API function), 

204-205, 269, 467-468 
DosStopSession (API function), 

204-205, 269, 469 

DosSubAlloc (API function), 237, 253, 
258, 469 

DosSubFree (API function), 237, 253, 

258, 469-470 

DosSubSet (API function), 237, 253, 

258, 470 

DosSuspendThread (API function), 
185,187,268,470-471 
DosSystemService (API function), 278, 
471-473 

DosTimerAsync (API function), 

272-273, 473-474 
DosTimerStart (API function), 

272-273, 474 

DosTimerStop (API function), 

272-273, 474 

DosUnlockSeg (API function), 253, 

256, 475 

DosWrite (API function), 141, 

224-225, 261-262, 271, 282, 475 
DosWriteAsync (API function), 

261-262, 475-476 

DosWriteQueue (API function), 229, 
231-232, 236-237,271,476 
DPATH (command line command), 43, 252 
drivers, device, 8, 84-91, 110-111 
dual-boot option, 32 
dual-mode programs, 95-111, 159-173 
developing, 165-173 
mechanism of, 160-164 
performance of, 164-165 
dynamic-link libraries, 35-36, 84-85, 
114-115,313-334 



advanced features, 327-330 
compiling, 324-325 
developing, 314-330 
linking, 326 
using, 330-334 

writing code for, in C, 321-323 
dynamic linking, 7-8, 55-60 
load-time vs. run-time, 59, 275-276, 
330-334 


E 

ENDLOCAL (command line 
command), 43 

entry conditions (of programs), 74-83, 
250-252 

in C programs, 80-83 
under MS-DOS, 74-75 
under OS/2, 75-80 
environment (program), 75-77 
error codes, 595-609 
error handling, 50-52, 134, 277-278 
exceptions (processor), 59, 134, 

277-278 

EXIT (command line command), 17, 
203-204 

expanded memory, 5-6, 105-106 
extended edition (of OS/2), 26-27, 30, 
32 

extended keyboard code, 301 
extended memory, 5-6, 105-106 
EXE file header, 160-162 
EXTPROC (command line command), 
43 


F 

/F (compiler option), 186, 190 
Family API, 31, 163, 168-170 
family programs. See dual-mode 
programs 

/Fb (compiler option), 173 


FOBS (configuration command), 35 
FILCOM (command line command), 
40 

file control blocks (FCB), 106 

file handles, 106, 259-263 

file I/O, 259-263 

file management, 263-266 

FILES (configuration command), 34 

files, system, 156-157 

fonts (video), 289-291 


G 

/GO (compiler option), 179 
/G2 (compiler option), 117 
generic I/O control commands. See 
device control 

global data segments, 328-329 
global descriptor table. See descriptor 
table, local vs. global 
GRAFTABLE (command line 
command), 42 

GPI (graphics programming interface), 
367 

graphics interface, 9. See also 
Presentation Manager 
graphics programs, 292, 367-368 
/Gs (compiler option), 324, 375 
/Gw (compiler option), 375 


H 

header files, 52-54, 115-116. See also 
OS2.H 

HELPMSG (command line command), 
40-41 

hooking interrupts, 103-105, 134 
hotkey 
monitor, 338 
system, 13, 15 

huge memory allocations, 67, 256-257 



I 

icons (Presentation Manager), 370 
idle-time priority class, 180-183 
IMPLIB (utility), 58, 314 
import libraries, 55-56, 326-327. See 
also DOSCALLS.LIB 
include files. See header files 
inheritance (by child processes), 
194-195 

initialization, of dynamic-link libraries, 
327-328 

instance data segments, 328-329 
interface, program. See API 
international support, 273-275 
interprocess communication, 7, 61-62, 
207-245, 270-271 
pipes, 223-229 
queues, 229-237 
semaphores, 212-223 
shared memory, 208-212 
signals, 237-245 

interrupt services. See MS-DOS, 
services; BIOS, services 
interrupt vectors, 134, 278 
IOPL (configuration command), 35, 

151 

IOPL (I/O privilege) segments, 35, 
84-85, 138, 147-151, 153 

J 

JOIN (command line command), 42 

K 

KbdCharln (API function), 300-302, 
318,477-478 

KbdClose (API function), 299-300, 

478 

KbdDeRegister (API function), 304, 

479 

KbdFlushBuffer (API function), 301, 
303,479 


KbdFreeFocus (API function), 

299-300, 479 

KbdGetCp (API function), 79, 305, 
479-480 

KbdGetFocus (API function), 299-300, 
480 

KbdGetStatus (API function), 80, 
303-304, 480-481 

KbdOpen (API function), 299-300, 482 
KbdPeek (API function), 301-302, 

482- 483 

KbdRegister (API function), 304, 

483- 485 

KbdSetCp (API function), 305, 486 
KbdSetCustXt (API function), 305, 

486 

KbdSetStatus (API function), 303-304, 
486-488 

KbdStringln (API function), 301-302, 
303,488 

KbdSynch (API function), 488-489 
KbdXlate (API function), 305, 489-490 
kernel (OS/2), 84-85 
kernel applications, 113-157 
keyboard, 298-305 
character input, 300-303 
character translation, 304-305 
function replacement, 304 
logical, 298-300 
status of, 303-304 
virtual, 13-15 


language support, 273-275 

LASTDRIVE (configuration 
command), 34 

LIBPATH (configuration command), 
35-36, 118 

LIM-EMS (expanded memory), 5-6, 
105-106 

linker definition file. See definition 
files 
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linking, 117-118 
dynamic, 7-8, 55-60 
of dynamic-link libraries, 326 
static (standard), 55-56, 60-61 
with definition files, 152 
local descriptor table, 63 
logical video buffer, 291-292 
/Lp (compile option), 117 


M 

machine status word (MSW), 105 
MAKE (utility), 119, 122 
MAXWAIT (configuration command), 
36, 78, 182 

MEMMAN (configuration command), 
36, 65-66 
memory 

expanded,5-6, 105-106 
extended, 5-6, 105-106 
shared, 208-212, 257-258 
virtual, 5-6, 62-68 
memory management, 252-259 
discardable segments, 255-256 
executing data, 259 
general, 254-255 
huge blocks, 256-257 
shared segments, 257-258 
subsegments, 258 
See also shared memory 
memory map (of OS/2), 23-25 
memory-resident programs, 100, 107, 
155-156 

memory requirements (of OS/2), 23 
message files, 274-275 
message queue (Presentation 
Manager), 372-374 
MKMSGF (utility), 275 
mode (video), 289-291 
modularity, 7-8 
monitors, 23, 276, 337-361 
mechanism, 338-341 
writing, 341-342 


MouClose (API function), 307, 490 
MouDeRegister (API function), 307, 

310, 491 

MouDrawPtr (API function), 306-307, 
491 

MouFlushQue (API function), 307, 491 
MouGetDevStatus (API function), 

307, 491-492 

MouGetEventMask (API function), 

307, 492-493 

MouGetHotKey (API function), 307, 
493 

MouGetNumButtons (API function), 

307, 493 

MouGetNumMickeys (API function), 

308, 494 

MouGetNumQueEl (API function), 

308, 493 

MouGetPtrPos (API function), 306, 
308, 494-495 

MouGetPtrShape (API function), 308, 

495- 496 

MouGetScaleFact (API function), 308, 
496 

MouInitReal (API function), 308, 496 
MouOpen (API function), 306, 308, 

496- 497 

MouReadEventQue (API function), 
306, 308, 497-498 

MouRegister (API function), 308, 310, 
498-500 

MouRemovePtr (API function), 306, 
308, 500-501 
mouse, virtual, 13-15 
mouse functions, 134-135, 305-310 
MouSetDevStatus (API function), 308, 

501 

MouSetEventMask (API function), 
306, 308, 501-502 

MouSetHotKey (API function), 308, 

502 

MouSetPtrPos (API function), 306, 
308, 502-503 



MouSetPtrShape (API function), 308, 
503-504 

MouSetScaleFact (API function), 308, 
504 

MouSynch (API function), 308, 504 
moving (of segments), 24-25, 36, 
64-66. See also virtual memory 
MS-DOS, 3-11, 17-18, 20-21, 26, 28, 
30, 49-50, 95-111 
converting MS-DOS to OS/2, 
122-138 

program entry under, 74-75 
services, 100-101, 124-129 
MSGBIND (utility), 275 
multitasking, 6-7, 61-62, 177-205 
of processes, 191-203, 268-269 
of screen groups, 203-205, 269 
of threads, 39, 178-191, 267-268 
multiuser systems, 6-7 

N 

national language support, 273-275 
NLSFUNC (command line command), 
40 

/NOD (linker option), 117-118 
/NOI (linker option), 117 

0 

operators, command line, 44-45 
OS2.H (header file), 52-54, 115-116, 
121 

OS2INIT.CMD (file), 33 
overcommitment (of memory), 65 

P 

pascal (C keyword), 52, 150, 325 
Pascal calling conventions, 52, 150 
PATCH (command line command), 
40-41 

PATH (environment variable), 76 


path (of files), 43 

PAUSEONERROR (configuration 
command), 37 

physical video buffer, 137, 292-294 
pipes, 223-229 

pop-ups, 14, 23, 156, 294-295. See also 
TSRs; background programs 
port I/O, 137-138 
preemption (of threads), 179-180 
Presentation Manager, 9, 26, 30-31, 
282, 363-375 

program architecture, 371-375 
programmer interface, 370-371 
programs for, 364-368 
user interface shell, 368 
vs. kernel, 366-368 

PRINT (command line command), 106 
print queue, 106. See also SPOOL 
PRIORITY (configuration command), 
37,78,183 

priority (of threads), 36-37, 180-183 
privilege (of segments), 64, 68-73 
processes, 13, 19, 191-203, 268 
program segment prefix (PSP), 75, 81 
Programmer’s Toolkit (Microsoft), 
52-53 

PROMPT (environment variable), 76 
protected mode, 4-5 
protected mode applications, 113-157 
protected mode screen group, 13-20, 

37, 48 

protection, 66-67 
protection enable (PE) bit, 105 
PROTECTONLY (configuration 
command), 20, 37, 96 
PROTSHELL (configuration 
command), 33, 37 
PS/2 machines, 28 


Q 

queues, 229-237 
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R 

real mode, 4-5 

real mode screen group, 20-21, 28, 37, 
48,95-111 
real-time clock, 108 
redirection (of file I/O), 45, 142-143, 
201-202 

reentrant code, 186-187, 190 
regular edition (of OS/2), 26-27 
regular priority class, 180-183 
REM (configuration command), 38 
replacement of functions 
keyboard, 304 
mouse, 310 
video, 295-296 

resident programs, 100, 107, 155-156 
RMSIZE (configuration command), 
20, 25, 38, 96 
ROM BIOS. See BIOS 
RUN (configuration command), 
22-23, 155, 342 

run-time dynamic linking, 275-276 


S 

SAA (systems application 
architecture), 26, 367 
scheduling (of threads), 36-37, 39, 
178-183 

screen, virtual, 13-15 
screen group, 10-21, 203-205, 269 
protected mode, 13-20, 37, 48 
real mode, 20-21, 28, 37, 48, 95-111 
screen I/O. See video I/O 
scrolling (of screen), 288-289 
segment descriptor, 63-64. See also 
virtual memory 

segment selector, 63-64. See also 
virtual memory 
segments (memory), 62-73 
SELECT (command line command), 
40 


selector, segment, 63-64. See also 
virtual memory 
semaphores, 187, 212-223 
example of use, 218-223 
for flagging events, 217-218 
for protecting critical sections, 

215-217 

RAM vs. system, 212, 214-215 
serial port, 41 
session. See screen group 
session manager, 10-13 
SET (command line command), 76 
SETCOM40 (command line 
command), 40-42 
SETLOCAL (command line 
command), 44 

SHARE (command line command), 40 
shared memory, 208-212, 257-258 
giveaway, 211-212 
named, 210-211 
signals, 237-245 

SHELL (configuration command), 39 
SLIBCEP.LIB (file), 117-118 
SORT (command line command), 
201-203, 226, 228 

SPOOL (command line command), 44, 
106, 109-110 

stack, for multiple threads, 186 
STACKS (configuration command), 34 
standard device handles, 142-143, 
201-202, 226-228 

START (command line command), 
16-17, 44, 203 

STARTUPCMD (file), 32-33 
startup information. See entry 
conditions (of programs) 
string I/O (video), 286-288 
stub program, 160-163 
subsegment allocation, 258 
SWAPPATH (configuration 
command), 39 

swapping (of segments), 5-6, 36, 39, 
64-66. See also virtual memory 



T 

Task Manager (of the Presentation 
Manager), 368 

threads, 18-20, 39, 178-191, 267-268 
THREADS (configuration command), 
39, 179 

time-critical priority class, 180-183 
time management, 272-273 
TIMESLICE (configuration 
command), 39, 78, 180 
TRACE (configuration command), 40 
TRACEBUF (configuration 
command), 40 

TSRs (terminate-and-stay-resident 
utilities), 100, 107, 155-156 


U 

UNIX, 6 


¥ 

versions 

of MS-DOS, 106 
of OS/2, 25-27 
video buffer 
logical, 291-292 
physical, 137, 292-294 
video I/O, 263, 282-298 
character and attribute display, 
283-285 

cursor control, 285-286 
logical buffer management, 291-292 
mode and font control, 289-291 
physical buffer management, 292-294 
pop-up screen management, 294-295 
replacement of functions, 295-296 
scrolling, 288-289 
string I/O, 286-288 
video mode, 289-291 
Vio functions, advanced, 370 
VioDeRegister (API function), 

295-296, 505 


VioEndPopUp (API function), 
294-295, 349-351, 358, 505 
VioGetAnsi (API function), 80, 505 
VioGetBuf (API function), 291-292, 
505-506 

VioGetConfig (API function), 80, 
289-290, 506-507 

VioGetCp (API function), 289, 291, 
507 

VioGetCurPos (API function), 80, 
285, 507-508 

VioGetCurType (API function), 80, 
285, 508 

VioGetFont (API function), 80, 289, 
291,508-509 

VioGetMode (API function), 80, 
289-290, 509-510 
VioGetPhysBuf (API function), 

292- 293, 510 

VioGetState (API function), 80, 
289-290, 511-512 
VioModeUndo (API function), 

293- 294, 512 

VioModeWait (API function), 

293-294, 512-513 

VioPopUp (API function), 294-295, 
349-350, 358, 513 

VioPrtSc (API function), 297-298, 513 
VioPrtScToggle (API function), 
297-298,514 

VioReadCellStr (API function), 
286-288, 316, 323, 514 
VioReadCharStr (API function), 
286-287, 358, 514-515 
VioRegister (API function), 295-296, 
515-519 

VioSavRedrawUndo (API function), 
293,519 

VioSavRedrawWait (API function), 
293,519-520 

VioScrLock (API function), 293-294, 
520 

VioScrollDn (API function), 288-289, 
520-521 
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VioScrollLf (API function), 288, 

521- 522 

VioScrollRt (API function), 288, 522 
VioScrollUp (API function), 288, 

522- 523 

VioScrUnLock (API function), 
293-294, 523 

VioSetAnsi (API function), 296-297, 

523- 524 

VioSetCp (API function), 289, 291, 

524 

VioSetCurPos (API function), 285, 

319, 524 

VioSetCurType (API function), 285, 

525 

VioSetFont (API function), 289, 291, 

525- 526 

VioSetMode (API function), 289-290, 

526- 527 

VioSetState (API function), 289-290, 

527- 528 

VioShowBuf (API function), 291-292, 
528 

VioWrtCellStr (API function), 
286-287, 317, 323, 528-529 
VioWrtCharStr (API function), 
286-287, 529 

VioWrtCharStrAtt (API function), 
286-287, 529-530 


VioWrtNAttr (API function), 80-81, 
353, 358, 530 

VioWrtNCell (API function), 283-285, 
319,530-531 

VioWrtNChar (API function), 283, 
317,531 

VioWrtTTy (API function), 122, 
286-287, 296-297, 531-532 
virtual keyboard, 13-15 
virtual memory, 5-6, 62-68 
virtual mode. See protected mode 
virtual mouse, 13-15 
virtual screen, 13-15 


W 

windows (Presentation Manager, parts 
of), 369-370 

Windows (Microsoft), 9, 26, 28-31 
Windows Presentation Manager. See 
Presentation Manager 
window procedures (Presentation 
Manager), 372, 374 


Z 

/Zp (compiler option), 117, 121 
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OTHER OPERATING 
SYSTEMS AND 
ENVIRONMENTS 

Essential OS/2 

Judd Robbins 

367pp. Ref. 478-X 

This introduction to OS/2 for new and pro¬ 
spective users offers clear explanations of 
multitasking, details key OS/2 commands 
and functions, and updates current DOS 
users to the new OS/2 world. Details are 
also given for users to run existing DOS 
programs under OS/2. 

Programmer's Guide to OS/2 

Michael J„ Young 

400pp. Ref. 464-X 

This concise introduction gives a com¬ 
plete overview of program development 
under OS/2, with careful attention to new 
tools and features. Topics include MS- 
DOS compatibility, device drivers, serv¬ 
ices, graphics, windows, the LAN 
manager, and more. 

Programmer's Guide to GEM 
Phillip BaSma/WIISiam FitSer 
504pp. Ref. 297-3 

GEM programming from the ground up, 
including the Resource Construction Set, 
ICON Editor, and Virtual Device Interface. 
Build a complete graphics application 
with objects, events, menus, windows, 
alerts and dialogs. 

Programmer's Guide to TopView 
Alan R. Miliar 
280pp. Ref. 273-6 

A guided tour through every features of 
the TopView multitasking, windowed, 
operating environment for the IBM PC, 
with programming techniques and 


examples showing proper use of system 
resources. Includes assembly-language 
programming. 

Power User's Guide to Hard 
Disk Management 
Jonathan Kamin 

315pp. Ref. 401-1 

Put your work, your office or your entire 
business literally at your fingertips, in a cus¬ 
tomized, automated MS-DOS work environ¬ 
ment. Topics include RAM disks, extended 
and expanded memory, and more. 

Programmer's Guide to 

Windows 

(Second Edition) 

David Durant/Geta Carlson/Pais! Yao 

750pp. Ref. 496-8 

The first edition of this programmer’s 
guide was hailed as a classic. This new 
edition covers Windows 2 and Windows/ 
386 in depth. Special emphasis is given to 
over fifty new routines to the Windows 
interface, and to preparation for OS/2 
Presentation Manager compatibility. 

The CP/M Handbook 

Rodnay Zaks 

320pp. Ref. 048-2 

The definitive introduction and reference 
guide to the CP/M and MP/M operating 
systems, for users at all levels. With tutori¬ 
als on file handling, PIP and the editor, 
programming information, and a com¬ 
plete reference section. 

Mastering CP/M 

Alan R. Miller 

398pp. Ref. 068-7 

An advanced guide to using, altering and 
adding features to CP/M, with an intro¬ 
duction to macro programming and a 
useful macro library. Full details on BIOS 
and BDOS operations, and the 8080 and 
Z80 instruction sets. 



The CP/M Plus Handbook 

Alan R. Miller 

248pp. Ref. 158-6 

Easy-to-read chapters show readers how 
to use the transient commands, take 
advantage of the features of the system 
editor, speed up operations with the auto¬ 
matic file search path, and get the most 
out of CP/M Plus. 


DOS 


ABC's of MS-DOS 
(Second Edition) 

Alan R. Miller 

233pp. Ref. 493-3 

This handy guide to MS-DOS is all many 
PC users need to manage their computer 
files, organize floppy and hard disks, use 
EDLIN, and keep their computers orga¬ 
nized. Additional information is given 
about utilities like Sidekick, and there is a 
DOS command and program summary. 
The second edition is fully updated for 
Version 3.3. 

Mastering DOS 

Judd Robbins 

572pp. Ref. 400-3 

“The most useful DOS book.” This four- 
part, in-depth tutorial addresses the 
needs of users at all levels. Topics range 
from running applications, to managing 
files and directories, configuring the sys¬ 
tem, batch file programming, and tech¬ 
niques for system developers. A major 
cook. 

MS-DOS Handbook 
(Third Edition) 

Richard Alien King 

362pp. Ref. 492-5 

This classic has been fully expanded and 
revised to include the latest features of 
MS-DOS Version 3.3. Two reference 
books in one, this title has separate sec¬ 
tions for programmer and user. Multi-DOS 
partitons, 3 1 /2disk format, batch file call 
and return feature, and comprehensive 
coverage of MS-DOS commands are 
included. 


MS-DOS Power User's Guide, 
Volume I 
(Second Edition) 

Jonathan Kamin 
482pp. Ref. 473-9 

A fully revised, expanded edition of our 
best-selling guide to high-performance 
DOS techniques and utilities-with details 
on Version 3.3. Configuration, I/O, direc¬ 
tory structures, hard disks, RAM disks, 
batch file programming, the ANSI.SYS 
device driver, more. 

MS-DOS Power User's Guide, 
Volume SI 

Martin Waterhouse/Jonathan Kamin 

350pp, Ref. 411-9 

A second volume of high-performance 
techniques and utilities, with expanded 
coverage of DOS 3.3, and new material 
on video modes, Token-Ring and PC Net¬ 
work support, micro-mainframe links, 
extended and expanded memory, multi¬ 
tasking systems, and more. 

Performance Programming 
Under MS-DOS 
Michael J. Young 

436pp. Ref. 420-8 

Practical techniques for maximizing perfor¬ 
mance in MS-DOS software by making 
best use of system resources. Topics 
include functions, interrupts, devices, multi¬ 
tasking, memory residency and more, with 
examples in C and assembler. 

The ABC's of PO-OOS 

A!an R. Miller 

231pp. Ref. 438-0 

A beginner’s guide to PC-DOS for users 
of the IBM PC and compatibles-every¬ 
thing from working with disks and files, to 
using built-in commands, customizing the 
system, recovering from errors, and add¬ 
ing some handy utilities. 

Essential PC-DOS 
(Second Edition) 

MyriS Clement Shaw/ 

Susan Soltis Shaw 

332pp. Ref. 413-5 

An authoritative guide to PC-DOS, includ¬ 
ing version 3.2. Designed to make experts 



out of beginners, it explores everything 
from disk management to batch file 
programming. Includes an 85-page 
command summary. 

The IBM PC-DOS Handbook 
(Third Edition) 

Richard Alien King 
350pp. Ref. 512-3 

A guide to the inner workings of PC-DOS 
3.2, for intermediate to advanced users 
and programmers of the IBM PC series. 
Topics include disk, screen and port con¬ 
trol, batch files, networks, compatibility, 
and more. 

DOS instant Reference 

SYBEX Prompter Series 

Greg Harvey/Kay Yarborough Nefson 

220pp. Ref. 477-1; 4 3/4x8 
A complete fingertip reference for fast, 
easy on-line help:command summaries, 
syntax, usage and error messages. Orga¬ 
nized by function-system commands, 
file commands, disk management, direc¬ 
tories, batch files, I/O, networking, pro¬ 
gramming, and more. 

ASSEMBLY 

LANGUAGE 


Programming the 8086/8088 
James W. Coffron 
311pp. Ref. 120-9 

A concise introduction to assembly- 
language programming for 8086/8088- 
based systems, including the IBM PC. 
Topics include architecture, memory organi¬ 
zation, the complete instruction set, inter¬ 
rupts, I/O, and IBM PC BIOS routines. 

Programming the 80288 
Co Vieillefonid 
487pp. Ref. 277-9 

In-depth treatment of assembly-level pro¬ 
gramming for the IBM PC/AT’s 80286 
processor. Topics include system archi¬ 
tecture, memory management, address 
modes, multitasking and more; plus a 
complete reference guide to the instruc¬ 
tion set. 


Programming the 80386 

John H. Crawford/ 

Patrick P. GeBsinger 
775pp. Ref. 381-3 

A detailed tour of the 80386 for assembly- 
language programmers. Topics include 
registers, data types and instruction 
classes, memory management, protec¬ 
tion models, multitasking, interrupts, the 
numerics coprocessor, and more. 

DOS Assembly Language 

Programming 

Alan R. Miller 

365pp. Ref. 487-9 

This book covers PC-DOS through 3.3 
and gives clear explanations of how to 
assemble, link, and debug 8086, 8088, 
80286, and 80386 programs. The 
example assembly language routines are 
valuable for students and programmers 
alike. 

Programming the 68080 

Steve Williams 

539pp. Ref. 133-0 

This tutorial introduction to assembly- 
language programming covers the com¬ 
plete 68000 architecture and instruction 
set, as well as advanced topics such as 
interrupts, I/O programming, and interfac¬ 
ing with high-level languages. 

Programming the 65816 

William Labiak 

370pp. Ref. 324-4 

A step-by-step course in assembly lan¬ 
guage programming for the Apple IIGS 
and other 65816-based systems, from 
first concepts to complete applications. 
Topics include addressing, I/O, data 
structures, 6502 emulation and the 
65802. 

Programming the 6809 

Rodnay Zaks/William Labiak 

362pp. Ref. 078-4 

A step-by-step course in assembly- 
language programming for 6809-based 
home computers. Covers hardware orga¬ 
nization, the instruction set, addressing, 
I/O, data structures, program develop¬ 
ment and complete sample applications. 



Programming the 6502 
Rodnay Zaks 
408pp. Ref. 135-7 

The best-selling, step-by-step course in 
assembly-language programming for the 
6502 chip used in Apple, Atari and Com¬ 
modore computers. From basic concepts 
to architecture, instruction set, address¬ 
ing, I/O, sample applications and more. 

Advanced 6502 Programming 
Rodnay Zaks 
292pp. Ref. 089-X 

Ten game program case studies demon¬ 
strate a variety of advanced, powerful 
programming techniques: generating 
square waves, random numbers, simulta¬ 
neous I/O, real time simulation, interrupts, 
artificial intelligence, and more. 

Programming the Z80 
(Third Edition) 

Rodnay Zaks 

624pp. Ref. 069-5 

A self-teaching guide to assembly-language 
programming for the wide range of Z80- 
based microcomputers. Includes the 
Z80 architecture and instruction set, 
addressing, I/O techniques and devices, 
data structures and sample programs. 

Z80 Applications 

dames W, Coffron 

295pp. Ref. 094-6 

A handbook for assembly-language 
programmers on the principles of Z80 
hardware operations. Topics include 
using ROM, static and dynamic RAM, I/O, 
interrupts, serial communication and 
several specific LSI peripheral devices. 

LANGUAGE 

Introduction to Turbo Pascal 
(Second Edition) 

Douglas S. Stivison 
Charles Edwards 
386pp. Ref. 414-3 

A newly revised and updated version of 
our bestselling hands-on introduction to 
Turbo Pascal. Topics range from program¬ 
ming fundamentals to data structures, 


graphics, sound, and more-all demon¬ 
strated in practical sample programs. 

Advanced Techniques 
in Turbo Pascal 
Charles G. Edwards 
309pp. Ref. 350-3 

This collection of system-oriented tech¬ 
niques and sample programs shows how to 
make the most of IBM PC capabilities using 
Turbo Pascal. Topics include screens, win¬ 
dows, directory management, the mouse 
interface, and communications. 

Turbo BASIC Instant Reference 
SYBEX Prompter Series 
Douglas Hergert 

393pp. Ref. 485-2 

This quick reference for programmers 
offers concise, alphabetical entries on 
every command - statement, metastate¬ 
ment, function, and operation-in the 
Turbo BASIC language with descriptions, 
syntax, and examples cross-referenced to 
related commands. 

Introduction to Turbo BASIC 

Douglas Hergert 

523pp. Ref. 441-0 

A complete tutorial and guide to this now 
highly professional language: Turbo 
BASIC, including important Turbo extras 
such as parameter passing, structured 
loops, long integers, recursion, and 8087 
compatibility for high-speed numerical 
operation. 

Advanced Techniques 
in Turbo Prolog 
Carl Townsend 

398pp. Ref. 428-3 

A goldmine of techniques and predicates 
for control procedures, string operations, 
list processing, database operations, 
BIOS-level support, program develop¬ 
ment, expert systems, natural language 
processing, and much more. 

Introduction to Turbo Prolog 

Carl Townsend 

315pp. Ref. 359-7 

This comprehensive tutorial includes sam¬ 
ple applications for expert systems, natu¬ 
ral language interfaces, and simulation. 



Covers every aspect of Prolog: facts, 
objects and predicates, rules, recursion, 
databases, and much more. 

Turbo Pascal Toolbox 
Frank Dutton 
405pp. Ref. 472-0 

This collection of tested, efficient Turbo 
Pascal building blocks gives a boost to 
intermediate-level programmers, while 
teaching effective programming by 
example. Topics include accessing DOS, 
menus, bit maps, screen handling, and 
much more. 

Introduction to Pascal: 

Including Turbo Pascal 
Rodnay Zaks 
464pp. Ref. 319-8 

This best-selling tutorial builds complete 
mastery of Pascal-from basic structured 
programming concepts, to advanced I/O, 
data structures, file operations, sets, 
pointers and lists, and more. Both ISO 
Standard and Turbo Pascal. 

Introduction to Pascal 
(Including UCSD Pascal) 

Rodnay Zaks 

420pp. Ref. 066-0 

This edition of our best-selling tutorial on 
Pascal programming gives special atten¬ 
tion to the UCSD Pascal implementation 
for small computers. Covers everything 
from basic concepts to advanced data 
structures and more. 

The Pascal Handbook 
Jacques Tiberghien 

483pp. Ref. 053-9 

The Pascal programmer’s definitive refer¬ 
ence, for both micro and mainframe ver¬ 
sions of Pascal. A to Z entries, complete 
with illustrations, cover every Pascal 
instruction, function, operator and 
reserved word in detail. 

Fifty Pascal Programs 
Bruce H. Hunter 
338pp. Ref. 110-1 

A valuable collection of programs for 
business, engineering, finance, games, 
and more, illustrating concepts of struc¬ 


tured programming, I/O techniques, tran¬ 
scendental functions, data type creation, 
sorting and searching, and much more. 

Your First BASIC Program 
Rodnay Zaks 

182pp. Ref. 092-X 

This illustrated, step-by-step introduction to 
computer programming in BASIC will have 
novices writing complete programs in a 
matter of hours. Covers everything from 
first concepts to loops and branches - all in 
plain language. 

Celestial BASIC: Astronomy on 
Your Computer 
Eric Burgess 

300pp. Ref. 087-3 

A complete home planetarium. This col¬ 
lection of BASIC programs for astronomi¬ 
cal calculations enables armchair 
astronomers to observe and identify on 
screen the configurations and motions of 
sun, moon, planets and stars. 

Mastering Turbo C 
Stan Kelly-Bootle 

400pp. Ref. 462-3 

No prior knowledge of C or structured pro¬ 
gramming is required for this introductory 
course on the Turbo C language and devel¬ 
opment environment by this well-known 
author. A logical progression of tutorials and 
useful sample programs build a thorough 
understanding of Turbo C. 

Systems Programming in Turbo C 
Michael J. Young 

365pp. Ref. 467-4 

An introduction to advanced program¬ 
ming with Borland’s Turbo C, and a gold¬ 
mine of ready-made routines for the 
system programmer’s library: DOS and 
BIOS interfacing, interrupt handling, win¬ 
dows, graphics, expanded memory, 
UNIX utilities, and more. 

Understanding C 
Bruce H. Hunter 

320pp. Ref. 123-3 

A programmer’s introduction to C, with 
special attention to implementations for 



microcomputers-both CP/M and MS- 
DOS. Topics include data types, storage 
management, pointers, random I/O, func¬ 
tion libraries, compilers and more. 

Mastering C 

Craig BoSon 

437pp. Ref. 326-0 

This in-depth guide stresses planning, 
testing, efficiency and portability in C 
applications. Topics include data types, 
storage classes, arrays, pointers, data 
structures, control statements, I/O and the 
C function library. 

Data Handling Utilities in C 

Robert A. Raddiffe/Thomas J. Raab 

519pp. Ref. 304-X 

A C library for commercial programmers, 
with techniques and utilities for data entry, 
validation, display and storage. Focuses 
on creating and manipulating custom log¬ 
ical data types: dates, dollars, phone 
numbers, much more. 


COMMUNICATIONS 


Mastering Crosstalk XVI 

Peter W. Gotten 

187pp. Ref. 388-0 

Recoup the cost of this book in a matter of 
hours with ready-made routines that 
speed up and automate your on-line data¬ 
base sessions. Tutorials cover every 
aspect of installing, running and customiz¬ 
ing Crosstalk XVI. 

Operating the IBM PC Networks 

Paul Berry 

363pp. Ref. 307-4 

The complete guide to planning, installing 
and using the IBM Token Ring and Broad¬ 
band networks. The book provides gen¬ 
eral discussion of network uses and 
possibilities, and step-by-step instructions 
for network tasks at all levels. 


HARDWARE 


The RS-232 Solution 

Joe Campbell 

194pp. Ref. 140-3 

A complete how-to guide to trouble-free 
RS-232-C interfacing from scratch. In- 
depth coverage of concepts, techniques 
and testing devices, and case studies 
deriving cables for a variety of common 
computers, printers and modems. 

Mastering Serial 
Communications 
Peter W. Gofton 

289pp. Ref. 180-2 

The software side of communications, 
with details on the IBM PC’s serial pro¬ 
gramming, the XMODEM and Kermit 
protocols, non-ASCII data transfer, 
interrupt-level programming and more. 
Sample programs in C, assembly lan¬ 
guage and BASIC. 

Microprocessor interfacing 
Techniques (Third Edition) 

Austin lesea/Rodnay Zaks 

456pp. Ref. 029-6 

This handbook is for engineers and hob¬ 
byists alike, covering every aspect of 
interfacing microprocessors with periph¬ 
eral devices. Topics include assembling a 
CPU, basic I/O, analog circuitry, and bus 
standards. 

From Chips to Systems: An 
Introduction to Microcomputers 
(Second Edition) 

Rodnay Zaks/ASexander Wolfe 

580pp. Ref. 377-5 

The best-selling introduction to microcom¬ 
puter hardware-now fully updated, 
revised, and illustrated. Such recent 
advances as 32-bit processors and RISC 
architecture are introduced and explained 
for the first time in a beginning text. 



Mastering Digital Device Control 
William G. Houghton 
366pp. Ref. 346-5 

Complete principles of system design 
using single-chip microcontrollers, with 
numerous examples. Topics include 
expanding memory and I/O, interfacing 
with multi-chip CPUs, clocks, display 
devices, analog measurements, and 
much more. 


SPREADSHEETS AND 

INTEGRATED 

SOFTWARE 


The ABC's of 1=2-3 
(Second Edition) 

Chris Gilbert/Laurie Williams 

245pp. Ref. 355-4 

Online Today recommends it as “an easy 
and comfortable way to get started with 
the program.” An essential tutorial for 
novices, it will remain on your desk as a 
valuable source of ongoing reference and 
support. For Release 2. 

Mastering 1-2-3 (Second 
Edition) 

Carolyn Jorgensen 

500pp. Ref. 528-X 

Get the most from 1-2-3 Release 2 with 
this step-by-step guide emphasizing 
advanced features and practical uses. 
Topics include data sharing, macros, 
spreadsheet security, expanded memory, 
and graphics enhancements. 

Lotus 1-2-3 Desktop Companion 
(SYBEX Ready Reference Series) 
Greg Ham/ey 
976pp. Ref. 501-8 

A full-time consultant, right on your desk. 
Hundreds of self-contained entries cover 
every 1-2-3 feature, organized by topic, 
indexed and cross-referenced, and sup¬ 
plemented by tips, macros and working 
examples. For Release 2. 


Power User's Guide 
to Lotus 1-2-3 

Peter Antoniak/E. Michael Lunsford 

368pp. Ref. 421-6 

This guide for experienced users focuses on 
advanced functions, and techniques for 
designing menu-driven applications using 
macros and the Release 2 command 
language. Interfacing techniques and 
add-on products are also considered. 

Lotus 1-2-3 instant Reference 

SYBEX Prompter Series 

Greg Harvey/Kay Yarborough Nelson 

296pp. Ref. 475-5; 4 3/4x8 
Organized information at a glance. When 
you don’t have time to hunt through hun¬ 
dreds of pages of manuals, turn here for a 
quick reminder: the right key sequence, a 
brief explanation of a command, or the 
correct syntax for a specialized function. 

Mastering Lotus HAL 

Mary V. Campbell 

342pp. Ref. 422-4 

A complete guide to using HAL “natural 
language” requests to communicate with 
T2-3 for new and experienced users. 
Covers all the basics, plus advanced HAL 
features such as worksheet linking and 
auditing, macro recording, and more. 

Simpson's 1-2-3 Macro Library 

Alan Simpson 

298pp. Ref. 314-7 

Increase productivity instantly with 
macros for custom menus, graphics, con¬ 
solidating worksheets, interfacing with 
mainframes and more. With a tutorial on 
macro creation and details on Release 2 
commands. 

Focus on Symphony Macros 

Alan Simpson 

239pp. Ref. 351-1 

An in-depth tutorial guide to creating, 
using, and debugging Symphony macros, 
including developing custom menus and 
automated systems, with an extensive 
library of useful ready-made macros for 
every Symphony module. 



Diskette Offer 


Companion Diskette 

The Companion Diskette contains all program listings in the Programmer’s 
Guide to OS/2, including all C, header, definition, assembler, and MAKE 
files. This diskette will enable you to make immediate use of these files for 
testing or modifying the example programs, or for developing your own 
OS/2 applications. 

OS/Tools 

OS/Tools is a set of software tools designed to give you a head start in develop¬ 
ing OS/2 applications. This tool set includes the following components: 

♦ Utilities: Includes an interactive screen designer for creating win¬ 
dows, menus, and full-screen displays; a utility for designing 
printed reports; a keyboard macro utility; and an enhanced ver¬ 
sion of the cut-and-paste program presented in Chapter 11. 

♦ Function library: Includes a complete set of video functions for 
managing screens, windows, menus, and data entry fields; func¬ 
tions for generating printed reports; and a set of useful utility 
functions. The function library is implemented as a dynamic-link 
module so that it can be called by any OS/2 program. 

♦ Source code: Complete, commented source code is provided for all 
utilities and functions. 

♦ Documentation: Thorough documentation for all utilities and 
functions is supplied in a ready-to-print file. 


ORDER FORM 

_ Copies of the Companion Diskette @ $19.50 each - 

_ Copies of OS/Tools (version 1.0) @ $39.50 each - 

_ California residents: add 6°7o sales tax - 

_ Shipping and Handling: add $2.50 ($5.00 foreign) per item - 

Total Order _ 

□ I would like to receive information on other development tools for MS-DOS and OS/2. 

Name --- 

Address_____ 

City/State/Zip--- 

All diskettes are in standard 5V4-inch IBM format. Please send a check for full payment payable 
to Michael J. Young (no purchase orders or bank cards; for foreign orders please send an interna¬ 
tional money order in U.S. dollars). Your software will be shipped immediately. Send order to: 

Michael J. Young 
RO. Box 5068 
Mill Valley, CA 94942 


SYBEX is not affiliated with Michael J . Young and assumes no responsibility for any defect in the disk 
or program. 





SYBEX Computer Books 
are different 


Here is why . . . 

At SYBEX, each book is designed with you in mind. Every manuscript is 
carefully selected and supervised by our editors, who are themselves 
computer experts. We publish the best authors, whose technical expertise 
is matched by an ability to write clearly and to communicate effectively. 
Programs are thoroughly tested for accuracy by our technical staff. Our 
computerized production department goes to great lengths to make 
sure that each book is well-designed. 

In the pursuit of timeliness, SYBEX has achieved many publishing firsts. 
SYBEX was among the first to integrate personal computers used by 
authors and staff into the publishing process. SYBEX was the first to 
publish books on the CP/M operating system, microprocessor interfacing 
techniques, word processing, and many more topics. 

Expertise in computers and dedication to the highest quality product 
have made SYBEX a world leader in computer book publishing. Trans¬ 
lated into fourteen languages, SYBEX books have helped millions of 
people around the world to get the most from their computers. We hope 
we have helped you, too. 

For a complete catalog of our publications: 

SYBEX, Inc. 2021 Challenger Drive, #100, Alameda, CA 94501 
Tel: (415) 523-8233/(800) 227-2346 Telex: 336311 
Fax: (415) 523-2373 




The 

OS/2 API 
Functions 


Continued 


♦ Family API functions that 
operate identically in real 
and protected modes 

0 Family API functions that 
operate differently in real 
and protected modes 


Miscellaneous Dos 
Functions 

♦ DosBeep 
DosPTrace 
DosSystemService 

Displaying Characters and 
Attributes on the Screen 
VioWrtNAttr 

* VioWrtNCell 

* VioWrtNChar 

Controlling the Cursor 

# VioGetCurPos 

# VioGetCurType 

♦ VioSetCurPos 

♦ VioSetCurType 

Beading and Writing 
Strings on the Screen 

♦ VioReadCellStr 

♦ VioReadCharStr 

* VioWrtTTy 

$ VioWrtCellStr 

# VioWrtCharStr 

# VioWrtCharStrAtt 

Scrolling Areas 
of the Screen 

# VioScrollDn 
$ VioScrollLf 

♦ VioScrollRt 
+ VioScrollUp 

Managing the Video State 
and Character Fonts 
VioGetConfig 
VioGetCp 
VioGetFont 
$ VioGetMode 
VioGetState 
VioSetCp 
VioSetFont 


♦ VioSetMode 
VioSetState 

Managing the Logical 
Screen Buffer 

♦ VioGetBuf 

^ VioShowBuf 

Managing the Physical 
Screen Buffer 

♦ VioGetPhysBuf 
VioModeUndo 
VioModeWait 
VioSavRedrawUndo 
VioSavRedrawWait 

0 VioScrLock 

♦ VioScrUnLock 

Managing Pop-up Screens 

VioEndPopUp 

VioPopUp 

Replacing Video Routines 

VioDeRegister 

VioRegister 

Miscellaneous 8 fm 

Functions 

YioGetAnsi 

VioPrtSc 

VioPrtScToggle 

VioSetAnsi 

Managing Logical 

Keyboards 

KbdClose 

KbdFreeFocus 

KbdGetFocus 

KbdOpen 




0 

0 

0 

0 

0 

0 


Obtaining Keyboard input 

KbdCharln 

KbdFlushBuffer 

KbdPeek 

KbdStringln 

Managing the Keyboard 
Status 

KbdGetStatus 

KbdSetStatus 

Replacing Keyboard 
Routines 
KbdDeRegister 
KbdRegister 

Managing Keyboard 

Character Translation 

KbdGetCp 

KbdSetCp 

KbdSetCustXt 

KbdXlate 

Managing the Mouse 

MouClose 

MouDeRegister 

MouDrawPtr 

MouFlushQue 

MouGetDevStatus 

MouGetEventMask 

MouGetHotKey 

MouGetN umButtons 

MouGetNumMickeys 

MouGetNumQueEl 

MouGetPtrPos 

MouGetPtrShape 

MouGetScaleFact 

MouInitReal 

MouOpen 

MouReadEventQue 


MouRegister 

MouRemovePtr 

MouSetDevStatus 

MouSetEventMask 

MouSetHotKey 

MouSetPtrPos 

MouSetPtrShape 

MouSetScaleFact 

MouSynch 


PROGRAMMER’S GUIDE 

to OS/2 


Programmer’s Guide to OS/2 is a comprehensive introduction to the 
principles and techniques of software development under OS/2. The 
book is based on the final released versions of OS/2 Programmer’s 
Tool Kit, Microsoft C (5.1), and Macro Assembler (5.1). Whether 
you’re a programmer seeking specific techniques, or just looking for a 
deeper understanding of the new OS/2 environment, this is the place to 
turn for: 

Clear explanations of underlying concepts and system architecture—with 
special emphasis on the differences between MS-DOS and OS/2. 

A step-by-step approach to programming—with plenty of concrete 
exampleSo Separate, detailed chapters show how to: 

• write an MS-DOS program for the OS/2 compatibility box 
® program specifically for OS/2’s protected mode 

• create software that operates under both MS-DOS and OS/2 
® create a full-fledged, multitasking OS/2 application 

• use OS/2’s interprocess communication facilities to synchronize 
concurrent tasks 

Complete reference documentation on the OS/2 application program 
interface, including concise summaries of the OS/2 kernel functions, 
and special OS/2 functions for the screen, the keyboard and the mouse. 
Appendices provide quick reference to OS/2 service calls, I/O control 
functions, and error codes. 

Detailed treatment of advanced and specialized topics, including: 

• writing and using dynamic-link libraries 

® creating OS/2 monitors, to implement background utility 
software 

• an introduction to the Presentation Manager, OS/2’s windowed 
operating environment 

Sample programs are compatible with Microsoft C version 5.1 and 
the Microsoft OS/2 Programmer’s Toolkit. All are available on disk 
(sold separately). 


Praise for Michael J. Young’s 
Performance Programming under 
MS-DOS : 

“A good choice for C and assembly 
language programmers... 
well-written to show how to optimize 
your programs.” 

Computer Book Review 
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